Skip to content

Development Process

mavrovde edited this page Nov 8, 2026 · 5 revisions

Development Process

viafrei-api is developed in the open with the full, normal GitHub process. This page describes how changes are proposed, checked, released and documented.

Branches and pull requests

  • main is protected. Every change arrives through a pull request.
  • A pull request needs green required checks and an approving review from a code owner; stale approvals are dismissed when new commits arrive.
  • Linear history (squash merges), no force pushes, no branch deletion, conversations resolved before merge.
  • Pull-request titles follow Conventional Commits (feat:, fix:, docs: …), checked automatically, because releases are generated from them.
  • Issue and pull-request templates ask for the problem, the change, the evidence and the tests.

Continuous integration (every push and pull request)

Step Purpose
Formatting and dependency hygiene consistent code; no stray dependencies
Linting, scope lint, configuration lint code quality; nothing about data collection or internal names; no tunable literals
Regeneration diff typed queries, the OpenAPI document and the configuration reference must match the code
Tests with a PostGIS service container unit, mapping, role, cancellation and query-plan tests; coverage gate
Fuzz smoke a short fuzzing run on every parser
OpenAPI checks Spectral lint, oasdiff breaking-change diff against main, executed documentation examples
Documentation build the guide and the reference build cleanly
Image build and boot smoke the container starts, /readyz answers, Schemathesis and a short k6 run pass
Vulnerability check the language's vulnerability scanner over dependencies

All third-party actions are pinned by commit SHA, and Dependabot updates the pins.

As implemented in 0.2.0

The Go implementation (ADR-0001) runs these jobs in .github/workflows/ci.yml on every pull request and push to main; every job is bounded by a timeout and nothing is retried (TST-017):

Job What it checks
Lint golangci-lint (with gosec, errorlint, depguard), actionlint with shellcheck
Unit and handler tests go test -race -shuffle=on -coverpkg=./...
Integration tests (PostGIS) the store, the read role and cancellation against a throwaway PostGIS container (testcontainers)
Coverage gate (100 % per package) the unit, integration and boot-smoke profiles merged; any package below 100 % fails (TST-001)
Generated files are current sqlc code, the configuration reference and the OpenAPI document
OpenAPI lint and breaking changes Spectral and oasdiff against the base
govulncheck reachable vulnerabilities in the module and the standard library
Image Hadolint, the multi-architecture build, /healthz of the built image, Trivy
Compose smoke the local stack with Schemathesis against the running API
SonarCloud analysis quality gate over the merged coverage profile
Requirement report every automated MUST row in the milestone's scope has a passing test ([[Testing Strategy

.github/workflows/security.yml runs on every pull request, on main and weekly: CodeQL, gitleaks over the history, Snyk, dependency review, a dependency-licence check, and an OWASP ZAP API scan against the compose stack. CI adds govulncheck, and the Image job Hadolint and Trivy on the built image. One tool per kind of check: a second tool reporting the same class of finding is not run. Every scanner that can write SARIF uploads it to code scanning; the tools and thresholds are on Spec: Secure SDLC and Supply Chain. Scorecard runs on main and weekly. A job that needs a secret the run does not have fails and names the secret. Releases: Release Process; the image: Container and Deployment.

Security scanning

Tool When
CodeQL every push and pull request, and weekly
Dependency review every pull request; fails on high severity or a disallowed licence
Dependabot weekly grouped version updates, plus security updates
Secret scanning with push protection always, including a custom pattern for ViaFrei key prefixes
Container image scan (Trivy) every pull request and every release; fails on high or critical findings
OpenSSF Scorecard weekly
Private vulnerability reporting always available to reporters

Releases

The flow as implemented is on Release Process.

  • release-please reads Conventional Commits on main and maintains a release pull request with the changelog.
  • Merging it creates the semantic-version tag and the GitHub Release.
  • The release publishes a multi-architecture container image to the GitHub Container Registry with build provenance, an SBOM and a keyless signature, scanned before publication.
  • The API's version is kept in step with the ViaFrei platform's version: a version-sync pull request updates the read-contract file, the parity fixtures and the platform version, and tells release-please which version to cut. GET /v1/meta reports both versions and the contract version.
  • The platform's deployment check reports a mismatch between the deployed API and the platform's schema.

Documentation

  • A getting-started guide (obtain a key, make a first call), concept pages (attribution, errors, limits, tiers, versioning), a page per error type, and the OpenAPI reference rendered with Scalar.
  • Published to GitHub Pages from main on every release, at https://mavrovde.github.io/viafrei-api/: the release workflow's pages job builds the site from the tag (scripts/docs-build.sh) and reads it back until it serves that version. Today the site holds the guide (the README and the configuration, container and security-check pages) and the OpenAPI reference, rendered by Redocly into one self-contained page (no script is loaded from elsewhere when it is read); the getting-started and concept pages above join it as they are written.
  • Examples are executed in CI against fixtures; the configuration reference is generated from code.

Nightly and weekly

Nightly: long fuzzing runs, the full benchmark, deep Schemathesis runs, load, soak and chaos scenarios on the test stack. Weekly: the full DAST scan, stress and spike runs, scheduled dependency scans and Scorecard. A nightly or weekly failure opens or updates an issue and blocks the next release until resolved.

Testing

The testing approach is the Testing Strategy; each milestone has entry and exit criteria on the Test Plan; the gate per stage is on Test Environments and Quality Gates. In short:

  • tests are written with the change, carry the requirement IDs they verify and are shown to fail before the fix (TST-003, TST-013);
  • tests never reach a live data source or production, and use only the synthetic fixture set (Test Data Management);
  • every gate fails closed and prints what it checked; no test is retried to green, flaky tests are quarantined with an issue;
  • defects follow Defect Management, and each release publishes a test completion report.

Definition of done

A change is done when its tests, documentation and changelog entry are in the same pull request, every required check is green, a reviewer has approved it, and nothing in it describes how data is collected.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally