Contributing

Environment

poetry install
poetry run pre-commit install

The project targets Python 3.12+.

Quality checks

Before opening a merge request:

poetry run ruff check .
poetry run ruff format --check .
poetry run mypy src tests
poetry run pytest
poetry run mkdocs build --strict

Workflow

1. Branch from main.
2. Keep the change focused on one coherent concern.
3. Add or update tests for behavioural changes.
4. Run the local quality suite.
5. Open a merge request into main.
6. Merge only after required checks pass when GitLab compute capacity is available.

CI/CD

The repository's GitLab CI is split into local includes:

.gitlab-ci.yml
.gitlab/ci/quality.yml
.gitlab/ci/security.yml
.gitlab/ci/release.yml
.gitlab/ci/docs.yml

Merge requests run code-quality, test, security, package-build, and documentation checks. The default branch additionally deploys documentation through GitLab Pages.

Documentation

Documentation lives under docs/ and is configured by mkdocs.yml.

Keep CLI examples aligned with the actual parser in src/gitlab_project_audit/cli.py. Rule IDs documented in the catalogue must match the rule implementations exactly.

Releases

Tagged releases must follow the release workflow. Package versions and tags must match exactly before GitLab release artifacts are created.

Self-audit

After configuring GITLAB_TOKEN, run:

poetry run python scripts/self_audit.py

This uses the public CLI, checked-in self-audit policy, and regression baseline. See Self-audit.