CONTRIBUTING.md

# How to contribute

## Code of conduct

We follow the [Contributor Covenant](https://www.contributor-covenant.org) code
of conduct, please see the [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) document
for details.

## Preparing the development environment

Make sure you have development dependencies installed in your development
environment.

```
pip install -r requirements-dev.txt
```

## pre-commit hooks

We use [pre-commit](https://pre-commit.com/) to maintain and install pre-commit
hooks that should be executed before each commit.


Please install these required tools on your system:

* [hadolint](https://github.com/hadolint/hadolint) for linting the `Dockerfile`
* [shellcheck](https://www.shellcheck.net/) and
* [shfmt](https://github.com/mvdan/sh) to lint and validate shell scripts

Then install pre-commit hooks:

```
pre-commit install
```

Running `git commmit` for the first time after installing the hook usually takes a
little longer because `pre-commit` pulls it's hooks from upstream repositories.
You can find all hooks in `.pre-commit-config.yaml`.

In case you need to skip the execution of the pre-commit hooks (please don't!),
use `git commit --no-verify`.


## Adding dependencies

Make sure you update our `requirements.txt` file before you push your changes.
Whenever you need a new python package, add it to requirements.in and run

`pip-compile`

to generate an new `requirements.txt` which does not only pin the new package
but also its dependencies.

If the new package you are adding is only used by developers,
please add it to the `requirements-dev.txt` file.

## CI pipeline image

We use a custom disk image for the VPSs used by the CI pipeline. On this image,
the `install-kubernetes.yaml` playbook has already been applied, which usually
saves a few minutes of pipeline running time.

### What to do when I change a part of the `install-kubernetes.yaml` playbook?

Don't worry, the playbook *runs* in the CI (just faster, because usually
nothing needs to change). So if you make changes, you can test those in the CI
without problems.

If you want to start with a clean slate, however, you might want to change
`.gitlab/ci_scripts/create_vps.sh` and temporarily remove the `--disk-image-id`
argument.

#### Before you merge, make sure your changes are applied to a new custom image:

If you changed the `install-kubernetes.yaml` playbook, for example to upgrade
the k3s version in use, you'll want to generate a new disk image template and
use it. This is a manual process for now. Follow these steps:

1. Create a new VPS
   ```
   export HOST_NAME=baseimage$(date +'%Y%m%d')
   # Make sure you use your private ssh key id, 411 is the ssh key used in CI
   export SSH_ID=411
   python -m stackspin ${HOST_NAME} create --create-droplet --create-hostname ${HOST_NAME}.stackspin.net --ssh-key-id $SSH_ID --create-domain-records --subdomain ${HOST_NAME} stackspin.net
   ```

2. Accept ssh host key
   ```
   ssh root@${HOST_NAME}.stackspin.net
   ```

3. Run the following to install *only kubernetes* on the VPS:
   ```
   python3 -m stackspin ${HOST_NAME} install
   ```
4. Log into your machine and clean up the k3s server, then delete the cluster
   data:
   ```
   ssh root@${HOST_NAME}.stackspin.net
     # Clean up running containers and firewall
     /usr/local/bin/k3s-killall.sh
     # Remove k3s state
     rm -rf /var/lib/rancher/k3s
   ```
5. Log into Cosmos with the Stackspin account
6. Go to VPS Cloud -> VPS and shut down your VPS
7. Go to VPS Cloud -> Disk Images and click `Manage` for your VPSs disk image
   1. Change the Disk Label to something like `k3s-template-DATE`
   2. Set VPS to `-- not assigned --`
   3. Click save
   4. `Manage` the same image again
   5. Click 'make template'
   6. Choose "Linux Latest LTS" as the kernel
   7. Choose OS type Debian 11 (bullseye)
   8. Remember the disk image ID that you can see in the current URL as `id=...`
   9. Click save
8. Change the `--disk-image-id` argument in `.gitlab/ci_scripts/create_vps.sh`
   to your current disk-image-id **with a minus in front of it**. This is
   because custom images are negative integers, whereas Greenhost's disk images
   are positive integers
9. Remove the droplet

You are now ready to merge the changes you made to the `install-kubernetes`
playbook