Skip to content

Contributing to Polytropos

Quick Start

uv sync

Development Environment

Polytropos uses Nix with devshell to provide a reproducible development environment. This gives you Python, uv, and all required tools automatically.

  1. Install direnv for your shell
  2. Run direnv allow in the project root

The shell will automatically activate when you enter the directory.

Option 2: Without direnv

nix develop --impure

This directly enters the development shell without direnv.

Option 3: Without Nix

If you prefer not to use Nix, install uv manually and run:

uv sync

Running Tests

All tests must pass when you submit a merge request.

uv run pytest
nix flake check

Building Documentation

Start a local server with docs:

uv run mkdocs serve --livereload

Build it statically (done automatically by CD):

uv run mkdocs build

Commit Messages

Commit messages should follow the Conventional Commits specification. This is enforced by Commitizen.

Publishing Releases

Polytropos uses Commitizen for version management and automated changelog generation. Releases are published automatically when a git tag is pushed.

Creating a Release

To publish a new release:

cz bump --retry
git push --follow-tags

This command will:

  1. Update pyproject.toml with the new version
  2. Create an annotated git tag
  3. Push the commit and tags to the remote
  4. Trigger CD jobs that will publish the packages, as explained below

CI/CD Variables Required

To enable automatic publishing, the following CI/CD variables must be configured in GitLab (Settings > CI/CD > Variables):

Variable Description
PYPI_API_TOKEN_TEST API token for test.pypi.org
PYPI_API_TOKEN API token for pypi.org

The GitLab PyPI registry is published automatically using the CI job token (no additional configuration required).

For more details on the GitLab PyPI registry, see the GitLab PyPI documentation.

To install Polytropos from the GitLab registry, configure pip to use the registry URL:

pip install --index-url https://gitlab.example.com/api/v4/projects/80039447/packages/pypi/simple/ polyltropos

Publishing Order

When a tag is pushed, the wheel is published to:

  1. GitLab PyPI registry
  2. test.pypi.org
  3. pypi.org