Maintenance

Update Dependencies

As described earlier in this documentation, we support two different development environments:

  • nix shell with nix package manager

  • venv with pip package manager

We try to keep the installed packages in both environments as identical as possible. Since nixpkgs usually provides older versions than pip, this means that we let nixpkgs handle dependency resolution and are satisfied with the older versions from nixpkgs in both environments. If, exceptionally, nixpkgs has a newer version, we use the older version from pip in both environments, i.e. we have to maintain custom nix expressions for the affected packages.

This process is largely automated by the command python -m dev.update_dependencies. It updates the Python packages in the nix environment and then writes the discovered version numbers into the pip-consumable constraints.txt. To run the command, nix must be installed.

Then developers using pip can upgrade by running pip install -r requirements-dev.txt.

Change Dependencies

To add or remove a direct dependency, we do so (without specifying the version number) in the following files:

  • nix/pythonPackages/workers-control.nix

  • nix/devShell.nix

  • requirements.txt

  • requirements-dev.txt

Run python -m dev.update_dependencies afterwards.

Releases

Maintainers regularly release new versions of the app. Procedure:

  1. Increment the version number of our app in pyproject.toml and nix/pythonPackages/workers-control.nix (follow https://semver.org/spec/v2.0.0.html).

  2. Add a new entry to CHANGELOG.md (follow https://keepachangelog.com/en/1.1.0/).

  3. Copy the constraints from constraints.txt into the dependencies in pyproject.toml.

  4. Create a Pull Request with label “release”. This will trigger integration tests against the deployment repo. On failure, fix current branch or deployment repo.

  5. After merging: create a new git tag (scheme: git tag v1.2.3 -m "Release version 1.2.3") and push the tag. Pushing the vX.Y.Z tag triggers the publish-pypi.yml GitHub Actions workflow, which builds the sdist and wheel and uploads them to PyPi.

One-time PyPI release setup

Automated publishing uses PyPI Trusted Publishing (OIDC). Configure once by a maintainer:

  1. On PyPi, open the workers-control project and add a new GitHub trusted publisher with: Owner ida-arbeitszeit, Repository workers-control, Workflow publish-pypi.yml.

  2. On Github, restrict who can create the triggering tag: add a repository ruleset targeting tags matching v* and a bypass list limited to maintainers/admins.