# Contributing to Polytropos

## Quick Start

```bash
uv sync
```

## Development Environment

Polytropos uses [Nix](https://nixos.org/) with
[devshell](https://numtide.github.io/devshell/) to provide a reproducible development
environment. This gives you Python, uv, and all required tools automatically.

### Option 1: With direnv (Recommended)

1. Install [direnv](https://direnv.net/) 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

```bash
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:

```bash
uv sync
```

## Running Tests

All tests must pass when you submit a merge request.

```bash
uv run pytest
nix flake check
```

## Building Documentation

Start a local server with docs:

```bash
uv run mkdocs serve --livereload
```

Build it statically (done automatically by CD):

```bash
uv run mkdocs build
```

## Commit Messages

Commit messages should follow the
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
This is enforced by [Commitizen](https://commitizen-tools.github.io/commitizen/).

## Publishing Releases

Polytropos uses [Commitizen](https://commitizen-tools.github.io/) 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:

```shell
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](https://docs.gitlab.com/ee/ci/variables/)):

| Variable              | Description                                                         |
| --------------------- | ------------------------------------------------------------------- |
| `PYPI_API_TOKEN_TEST` | API token for [test.pypi.org](https://test.pypi.org/help/#apitoken) |
| `PYPI_API_TOKEN`      | API token for [pypi.org](https://pypi.org/help/#apitoken)           |

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](https://docs.gitlab.com/user/packages/pypi_repository/).

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

```shell
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](https://gitlab.com/moduon/polytropos/-/packages)
2. [test.pypi.org](https://test.pypi.org/)
3. [pypi.org](https://pypi.org/)
