Contributing to Primr¶
Thanks for your interest in contributing to Primr! This document provides guidelines for contributing.
README demo screenshot¶
The root README uses a placeholder CLI screenshot (docs/images/primr-demo.png)
with ExampleCo demo data only—no real company content. To regenerate after
editing the HTML mockup:
Source: docs/images/primr-demo-terminal.html. Requires Playwright Chromium
(uv run playwright install chromium). No network or model API calls.
Getting Started¶
- Fork the repository
- Clone your fork:
git clone https://github.com/YOUR_USERNAME/primr.git - Set up the development environment. Three options:
Option A - uv (recommended, fastest, reproducible):
cd primr
uv sync --locked --all-extras # matches the primary CI environment
uv run playwright install chromium
# run tooling without activating a venv:
uv run --no-sync pytest tests/test_architecture.py -q
uv run --no-sync ruff check src/primr/
# Complete verification: AGENTS.md, including filtered tests and coverage.
uv sync --locked rejects a lockfile that is stale relative to
pyproject.toml, then installs its exact pinned set so your environment
matches CI and other contributors. After changing dependencies in
pyproject.toml, run uv lock and regenerate the container exports below.
Use uv 0.13.5, the version pinned in CI; export formatting is part of
the reproducibility check. Install uv from https://docs.astral.sh/uv/ if you
don't have it. That uv release can download CPython only through 3.15.1.
CI installs 3.15.2, the newest stable patch, from
.github/python/cpython-3.15.2-downloads.json into the job workspace.
Transitive security floors in [tool.uv].constraint-dependencies protect
locked source, development, and exported container environments. They do
not become published wheel requirements; pip installations resolve their
own transitive versions. Keep constraints, the lock, and container exports
consistent when refreshing security dependencies. soupsieve 4.0.0
requires Python >=3.11.5, and that patch is the published
requires-python floor. Python 3.11 through 3.15 stay the supported
minors.
Option B - manual pip (cross-platform):
cd primr
python -m venv .venv
.venv\Scripts\activate # Windows
# or: source .venv/bin/activate # macOS/Linux
python -m pip install --no-deps "https://files.pythonhosted.org/packages/3f/06/3e4420302363fbb71be3c7f35ce042f54bfca330e3e66b3a2e3c4cca579f/pip-26.2.2-py3-none-any.whl#sha256=fd7f4dfa8190e014013b9f08f3e973f4e4c26ffd179a204895533a7254813a70"
pip install -e ".[dev]"
playwright install chromium
Option C - guided bootstrap (Windows-friendly):
setup_env.py auto-picks Python 3.11+ if your default is older, installs the editable package, downloads Playwright browsers, and adds the user Scripts dir to PATH on Windows. Useful for first-time contributors who hit the "which Python do I use?" issue.
- Copy
.env.exampleto.envand add your API keys (or runprimr initto walk through it).
Repository transfer and publishing¶
The canonical repository is https://github.com/pueo-labs/primr. Existing
checkouts should update their origin:
The PyPI package remains primr; pip, pipx, uv, and primr update continue
using that package name. Source metadata and README changes appear on PyPI
with the next separately approved release, not when this repository changes.
Do not re-upload or retag an existing release to change its metadata.
Before that release, verify the PyPI Trusted Publisher is configured with
owner pueo-labs, repository primr, workflow release.yml, and environment
pypi, matching .github/workflows/release.yml. Keep the environment's
release protections. Adding a publisher does not publish a release. See
PyPI's publisher setup.
The documentation destination is https://pueo-labs.github.io/primr/.
Confirm repository Pages settings use GitHub Actions and verify the Docs
workflow's deployment and canonical URL after merging a documentation change.
GitHub does not redirect Pages sites on transfer.
Keep package documentation links on the repository until any new site is
verified. Do not recreate the previous repository to host a redirect: doing
so removes GitHub's existing repository redirects. A legacy Pages redirect,
if needed, is a separate change to the old owner's Pages site.
Development Workflow¶
Dependency maintenance¶
main is the only long-lived branch. Review dependency updates together when
they share a resolver constraint, merge through a passing pull request, and
delete the completed feature branches. Scheduled pip-audit and Trivy checks
remain active. Grouped weekly update PRs cover uv, GitHub Actions, and container
base images, with separate groups for security fixes. Major updates stay separate
for deliberate compatibility review. There is no automatic merge policy.
Python proposals update the lockfile within the existing package requirements. Intentional compatibility caps, including the Ruff formatter line, need a separate reviewed manifest change. Automated proposals must not widen those caps while labeling the result a compatible update.
Treat update PRs as proposals. Review the upstream changes, apply the accepted changes on a maintainer-authored feature branch, regenerate both exports below, and run the affected compatibility and security gates. Link and close the original proposal once the maintainer PR lands. Preserve maintainer authorship without bot coauthor trailers; do not merge the proposal branch itself. This keeps review automation separate from the default branch's commit authorship.
After changing the dependency lock with uv 0.13.5, regenerate both checked-in container exports before running the release gate:
uv export --locked --no-dev --extra api --no-emit-project --no-header --no-annotate --output-file deploy/runtime-requirements.lock
uv export --locked --only-group release --prune cyclonedx-bom --prune twine --no-emit-project --no-header --no-annotate --output-file deploy/build-requirements.lock
uv run --no-sync pytest tests/test_supply_chain_pins.py -q
Commit pyproject.toml, uv.lock, and any changed exports together. A lockfile
update alone can leave the container build on older dependencies and fail CI.
Installer trust-store remediation (2026-10-22)¶
The emSign incident requires separate updates to application certifi, pip's
vendored bundle, UV's embedded roots, and the publisher's sigstore runtime.
Use UV 0.13.5 and pip 26.2.2 or newer. Our virtualenv floor is 21.14.12 so
new development environments also receive a repaired embedded pip. The setup
wizard and container stages hash-bootstrap pip before package-index downloads;
the release export includes the installer without adding it to application
runtime requirements. The publishing action is commit-pinned to 1.14.3,
whose upload/attestation runtime includes certifi 2026.10.19 and sigstore 4.5.1.
Refresh existing development environments with uv sync --locked --all-extras.
Rebuild existing containers using docker build --pull --no-cache; changed
source pins do not repair already-built images. CI uses a new cache namespace
and uncached container builds. Inspect pip in each virtual environment and in
pipx's shared installer environment separately; upgrading the application's
certifi or one Python environment does not repair every installer on a machine.
The Bash and PowerShell installers reject affected UV and hash-bootstrap
pipx installation and shared pip. primr update rejects an affected or
unverifiable selected installer before running its upgrade command.
Keep TLS verification enabled. For older pip installations, use the exact
hash-pinned bootstrap in the manual setup above before other downloads.
References: Python incident notice, UV advisory, and publishing action release.
Running Tests¶
# Run the ordinary local suite without manual or provider integration tests
uv run --no-sync pytest tests/ --ignore=tests/manual -m "not integration" -v
# Run a specific test file
uv run --no-sync pytest tests/test_core/test_cli.py -v
# Run the CI-scoped suite with branch coverage
uv run --no-sync pytest tests/ --ignore=tests/manual \
-k "not test_wait_times_out_when_no_change" -m "not integration" \
--cov=src/primr --cov-branch --cov-fail-under=81
Code Quality¶
Before submitting a PR, ensure your code passes the relevant local gates. CI is the authoritative gate, but these commands match the current shape closely for ordinary code changes:
# Linting
uv run --no-sync ruff check src/primr/
# Formatting
uv run --no-sync ruff format --check src/primr/ tests/
# Type checking
uv run --no-sync mypy src/primr/ --ignore-missing-imports --disable-error-code=import-untyped --exclude "src/primr/api/"
# Tests and branch coverage
uv run --no-sync pytest tests/ --ignore=tests/manual -x --tb=short -q -k "not test_wait_times_out_when_no_change" -m "not integration" --cov=src/primr --cov-branch --cov-fail-under=81
# Security scan (gated at medium severity in CI)
uv run --no-sync bandit -r src/primr -c .bandit --severity-level medium --confidence-level medium -q
# Dependency vulnerability audit
uv run --no-sync pip-audit
# Documentation
uv run --no-sync mkdocs build --strict
For narrow fixes, run the focused tests for the touched behavior first, then run the broader gates before opening the PR.
URL parser fuzzing¶
The primary Linux Python 3.13 CI job runs a 30-second coverage-guided
Atheris smoke test against the existing
primr.utils.validators.validate_url boundary used by single and batch CLI
requests. This uses Atheris's bundled libFuzzer engine, separately from the
Hypothesis property suite. It makes no HTTP or model calls. The target permits
only documented InputValidationError failures and checks accepted schemes,
authority and hostname, absent credentials, valid ports, unchanged content, and
idempotence.
A network audit hook fails attempted connections or DNS lookups.
The checked-in corpus covers valid HTTPS, IPv6 and Unicode hosts plus malformed ports, brackets, NFKC authority delimiters, credentials, schemes, and injection patterns, including an empty hostname with a port. Deterministic tests check each seed's expected acceptance and prove that the oracle catches a permissive validator. Fuzzing consumes arbitrary bytes with surrogate escaping and additionally exercises an HTTPS authority shape. Inputs are bounded to 4 KiB in CI; a smoke run is not exhaustive parser, SSRF, native-extension, or end-to-end research coverage.
The engine is a hash-pinned, binary-only CI tool in
tests/fuzz/requirements.txt, intentionally outside the application dependency
lock. Its single wheel supports Linux x86_64 CPython 3.13. No runtime package,
compiler, OSS-Fuzz enrollment, external account, or corpus-storage service is
required. CI installs it into a temporary target directory, reuses the already
locked application environment, copies seeds before mutation, and retains
crashing inputs and the engine log as a seven-day failure artifact. Update the
version and the matching wheel hash together when maintaining this tool.
The dependency-audit step checks this separate tool requirement as well.
The isolated tool install uses --no-config so application resolver constraints
are not interpreted as extra hash-locked tool requirements; the application
install continues to use uv sync --locked --all-extras.
To reproduce on that platform after setting up the usual development environment:
mkdir -p .agent/fuzz/tools .agent/fuzz/corpus .agent/fuzz/artifacts
uv pip install --no-config --python .venv/bin/python --target .agent/fuzz/tools \
--only-binary=:all: --require-hashes --no-deps -r tests/fuzz/requirements.txt
cp tests/fuzz/corpus/url/* .agent/fuzz/corpus/
PYTHONPATH="$PWD/.agent/fuzz/tools:$PWD/src:$PWD" PYTHONHASHSEED=0 \
uv run --no-sync python -m tests.fuzz.url_fuzzer \
-max_total_time=30 -timeout=5 -rss_limit_mb=512 -max_len=4096 -seed=150 \
-print_final_stats=1 -artifact_prefix="$PWD/.agent/fuzz/artifacts/" \
.agent/fuzz/corpus
uv run --no-sync pytest tests/test_fuzz_url_contract.py -q
Pass a saved crash file in place of the corpus directory to replay it. Review and minimize confirmed failures before adding permanent regression seeds. Scorecard v5.3.0's Python detector recognizes the target's actual Atheris import; detection alone does not prove a run passed. CI engine results provide that evidence.
Optionally install the pre-commit hooks so ruff + mypy run automatically on each commit (CI is still the authoritative gate):
Code Style¶
The canonical development contract - the single seams to use, the
no-new-giant-file rule, the verify-current-APIs rule, the CLI verb convention,
and the pre-PR slop check - lives in
AGENTS.md at the
repo root. Tools that read the agents.md format load it natively; Claude Code
loads it through the one-line CLAUDE.md import (@AGENTS.md). The guide for
agents that operate primr is
clients/primr-operator.md.
The essentials:
- Follow PEP 8 guidelines
- Use type hints for all function signatures
- Write docstrings for public functions and classes
- Keep functions focused and under 50 lines when possible
- Use the existing seam (async/console/logging/config/json/http) rather than introducing a second way to do the same thing
No Real Company Data in the Repo¶
Primr is a company-research tool, which makes it tempting to use real company names when writing examples, fixtures, eval results, sample reports, or commit messages. Don't. This applies to docs, code comments, test fixtures, prompt templates, eval artifacts, debug scripts, and git commit messages - anywhere that gets pushed to GitHub.
Use these placeholders instead:
| Use case | Placeholder |
|---|---|
| Generic example company name | Acme Corp |
| Domain for examples | acme.example or example.com |
| Alternate company (multi-company snippets) | ExampleCo |
| Fictional product / brand | Cirrus Fleet (or any made-up name) |
Vendor/technology names referenced as first-class product features are fine - Cloudflare in bot-protection detection, Snowflake / Databricks / Microsoft Fabric in the data-fabric strategy, AWS / Azure / GCP / NVIDIA as --platform options. The line is: real names as technical references OK; real names as research-subject examples not OK.
When in doubt, grep your PR before opening it:
If a real name slips into a commit message, fix it before the commit lands - rewriting messages after a tagged release means rewriting tags too.
Pull Request Process¶
CI and CodeQL cancel superseded validation for the same pull request. Push and scheduled runs use independent groups, preserving every main-commit result and release verification. Update the branch before requesting review so the final diff and the successful checks both belong to the current PR head.
- Create a feature branch:
git checkout -b feature/your-feature-name - Make your changes with clear, atomic commits
- Ensure all tests pass and code quality checks succeed
- Update documentation if needed
- Submit a PR with a clear description of changes
PR Guidelines¶
- Keep PRs focused on a single feature or fix
- Include tests for new functionality
- Update CHANGELOG.md for user-facing changes
- Reference any related issues
Reporting Issues¶
When reporting bugs, please include:
- Python version (
python --version) - Operating system
- Steps to reproduce
- Expected vs actual behavior
- Relevant error messages or logs
Feature Requests¶
Feature requests are welcome! Please:
- Check existing issues first to avoid duplicates
- Describe the use case and expected behavior
- Explain why this would be useful
Collaboration¶
Keep collaboration respectful and focused on technical quality.
Questions?¶
Feel free to open an issue for questions or discussions about the project.
License¶
By contributing, you agree that your contributions will be licensed under the Apache License 2.0.