Skip to content

Contributing to Junix

Quick Start

uv sync

Development Environment

Junix 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

Run a single test file:

uv run pytest tests/test_protocol.py -v

Run with coverage:

uv run pytest --cov=junix --cov-report=term-missing

Type-check only:

uv run mypy src/junix

Lint and format:

uv run ruff check src/junix tests
uv run ruff format src/junix tests

Building Documentation

Start a local server with docs:

uv run properdocs serve

Build it statically (done automatically by CD):

uv run properdocs build

Commit Messages

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

Publishing Releases

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

Creating a 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

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).

Publishing Order

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

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