Skip to content

Development Process

mavrovde edited this page Nov 1, 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.

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 (Grype) every release; fails on critical findings
OpenSSF Scorecard weekly
Private vulnerability reporting always available to reporters

Releases

  • 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.
  • Examples are executed in CI against fixtures; the configuration reference is generated from code.

Nightly

Long fuzzing runs, the full benchmark and deep Schemathesis runs.

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