Contributing

Thanks for your interest in piighost. This page summarises the contribution workflow. For the authoritative version, see CONTRIBUTING.md at the repository root.

Prerequisites

• Python 3.11+
• uv as package manager
• A GitHub account

Getting started

1. Fork the repository on GitHub.

2. Clone your fork locally:

   git clone https://github.com/YOUR-USERNAME/piighost.git
   cd piighost
   git remote add upstream https://github.com/Athroniaeth/piighost.git

3. Install dependencies:

   uv sync

Workflow

Create a branch

Always from master:

git checkout -b feat/my-feature

Follow the conventions

• Protocols at every pipeline stage keep components swappable.
• Frozen dataclasses for data models (Entity, Detection, Span).
• ExactMatchDetector in tests, never a real NER model in CI.
• Conventional commits through Commitizen (feat:, fix:, refactor:, etc.).

Local checks

Before opening a PR:

make format                          # fix the format and the lint with ruff
make lint                            # check without changing anything
uv run pytest                        # run the tests
uv run pytest tests/ -k "test_name"  # run a single test

make lint changes no file and fails on the first problem. It checks the format with ruff format --check, the lint with ruff check, the types with pyrefly, the security with bandit, then the documentation with the page audit script. make format fixes what ruff can fix.

Open the pull request

• Clear title following the Commitizen format.
• Description that explains the why rather than the what.
• Link the related issue (Fixes #42).
• Screenshots or output samples when relevant.

Extension points

The most common places to contribute without touching the core:

• New detector: implement the AnyDetector protocol. See Extending piighost.
• New regex pack: publish a pattern group on the piighost catalog, which a config then pulls by reference.
• New placeholder factory: implement AnyPlaceholderFactory.