Skip to content

Contributing

Contributions are welcome. The plugin is intentionally small in surface area — five model files, a handful of helpers, a few report views — so most fixes and enhancements touch one or two files.

Quick start

  1. Fork the repo on GitHub and clone your fork.
  2. Bring up the dev stack (see Development Environment).
  3. Make your change.
  4. Run the test suite (make test from development/).
  5. Run the linter (uvx ruff check src/ tests/ && uvx ruff format src/ tests/ from the repo root).
  6. Open a pull request against main.

Coding style

  • Ruff for lint + format. The config is in pyproject.toml. Test method docstrings are exempted (D102 in **/tests/*) — test names are the documentation.
  • Docstrings on public functions and classes, Google-style. Explain the why, not the what.
  • No "Claude Code" attribution in commit messages — the maintainer prefers clean professional messages.
  • CalVer commit pattern: Phase N: <terse summary>. New features land in numbered phases; bug fixes can use fix: prefix instead.

Tests

Two test trees:

  • tests/ — host-pytest tests that use conftest.py to mock Nautobot at import time. Used for shape / smoke tests that don't need a real Django stack.
  • src/nautobot_contract_models/tests/ — integration tests run via nautobot-server test inside the dev container. Used for everything that touches model behavior, queryset logic, or Job execution.

Add tests for any new behavior. The existing tests are organized by concern (test_calendar.py, test_cost.py, test_priority.py, test_anomaly.py, test_helpers.py, test_jobs.py, test_snapshot.py).

Migrations

Generated by nautobot-server makemigrations nautobot_contract_models from inside the dev container. Important: the dev container runs as uid=999 while the host typically runs as uid=1000, so makemigrations may fail with a PermissionError writing the migration file. If that happens, hand-write the migration following the pattern in 0006_* or 0007_*.

Always verify with:

nautobot-server makemigrations --check --dry-run nautobot_contract_models
# Expect: "No changes detected in app 'nautobot_contract_models'"

Pull request checklist

Before opening:

  • [ ] Tests pass (make test)
  • [ ] Ruff is clean (uvx ruff check src/ tests/ && uvx ruff format --check src/ tests/)
  • [ ] No new migrations are pending (makemigrations --check)
  • [ ] Browser-verified any UI change (Playwright or manual)
  • [ ] PLAN.md updated for new phase work
  • [ ] README.md updated if user-facing behavior changed
  • [ ] One of the existing memory entries doesn't already describe a similar issue / pattern (avoid duplicating gotchas)

Reporting bugs

Open an issue with:

  • Nautobot version (nautobot-server --version)
  • Plugin version (pip show nautobot-contract-models)
  • Database backend
  • Minimal reproduction steps
  • Full traceback if applicable