Maintenance
===========


.. _updating-dependencies:

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 :py:mod:`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:

#. Increment the version number of our app in :py:mod:`pyproject.toml`
   and :py:mod:`nix/pythonPackages/workers-control.nix` (follow https://semver.org/spec/v2.0.0.html).
#. Add a new entry to :py:mod:`CHANGELOG.md` (follow https://keepachangelog.com/en/1.1.0/).
#. Copy the constraints from :py:mod:`constraints.txt` into the dependencies in :py:mod:`pyproject.toml`.
#. Create a Pull Request with label "release". This will trigger integration tests against
   the `deployment repo <https://github.com/ida-arbeitszeit/workers-control-deployment>`_.
   On failure, fix current branch or deployment repo.
#. 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
<https://docs.pypi.org/trusted-publishers/>`_ (OIDC). Configure once by a maintainer:

#. 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``.
#. 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.