Skip to content

Development Workflow

This page describes how pynteracta is planned, versioned and documented as it evolves. It is the reader-facing summary of the project's process; the authoritative, detailed version lives in WORKFLOW.md at the repository root.

Status & audience

pynteracta is pre-1.0 and currently targets internal use / automations. The near-term focus is completing the read (GET) surface of the Interacta API — one endpoint group per minor release — before tackling write operations, an async client, or a strict-semver 1.0.

Planning documents

The project separates history, forward plans, build log and changelog into distinct files:

Document What it is
ROADMAP (ROADMAP.md) Living index: the version table, versioning policy, the full read-surface inventory, and the deferred backlog. The entry point for "what's next".
Specs (specs/vX.Y-*.md) One spec per version — endpoints, deliverables, acceptance criteria, open questions — written before the work and frozen once the version ships.
Foundation spec (specs/v0.1-foundation.md) The frozen historical design of the foundation that shipped as v0.1.0.
Progress log (PROGRESS.md) Append-only record of what was actually done, decisions taken, and follow-ups. Its top Version map reconciles milestone numbers against the released tags.
Changelog (CHANGELOG.md) User-facing, generated by git-cliff.

Where to look:

  • What is shipped today? → CHANGELOG.md and the latest shipped row of ROADMAP.md.
  • What is coming next? → ROADMAP.md + the active specs/ file.
  • How was something built / why? → PROGRESS.md.

Continuous integration

The project is hosted on GitHub. Every push and pull request runs lint, strict type-checking, the unit-test matrix (Python 3.12 and 3.13) with the 85% coverage gate, the contract tests, a distribution build and a strict docs build. Merges to main publish this site to GitHub Pages; pushing a v* tag builds the distribution once and publishes it both as a GitHub release (wheel + sdist attached) and to PyPI via trusted publishing (OIDC — no API token is stored in the repository).

Versioning policy

  • Pre-1.0, lenient semver. Every feature is a minor bump; even breaking changes bump the minor until 1.0.
  • Cadence: one read-endpoint group per minor release. See ROADMAP.md for the current objective and the backlog.
  • Strict-semver 1.0 is deferred until the read surface is complete and the API has been stable for a while. PyPI publication is not gated on it: releases are published from v0.9.4 onward, with Development Status :: 3 - Alpha carrying the stability signal.
  • Versions are computed from Conventional Commits by python-semantic-release; the changelog is generated by git-cliff.

The per-version workflow

  1. Plan — pick the next scope from the roadmap and write a new specs/vX.Y-<slug>.md (endpoints + DTOs, deliverables, acceptance criteria, open questions). Add a row to the roadmap table and link the spec.
  2. Branch — create a dedicated branch (feature_<slug> / m<n>_<slug> / bugfix_<slug>). Never work on main.
  3. Implement — façade model → resource method (explicit kwargs + a *_raw escape hatch) → CLI command → tests (unit + contract + a JSON fixture) → docs. Commit with Conventional Commits.
  4. Gate — ruff check ., ruff format --check ., mypy src, and pytest --cov --cov-fail-under=85 must all pass. The same checks run on every pull request through GitHub Actions.
  5. Log — append a milestone section to PROGRESS.md (Done / Decisions / Follow-ups) and record the answers to the spec's open questions.
  6. Release — merge to main; semantic-release cuts the tag and git-cliff updates the changelog. Pushing the tag triggers the release workflow, which builds the wheel and sdist and attaches them to the GitHub release. Mark the version ✅ in the roadmap and freeze its spec.

Adding a new endpoint

Regenerate the models (only if the swagger snapshot changed) → write or extend the façade model (extra="ignore", with .raw as the documented escape hatch) → add the resource method (explicit kwargs, plus a *_raw variant for callers holding a pre-built DTO) → add unit and contract tests plus a JSON fixture → expose it in the CLI through render_output so --output, --full, --fields, --web-url and --export compose automatically → update docs/cli.md and the relevant docs/api/*.md. The full recipe is in CONTRIBUTING.md.