Delivery process
This document describes the repository evidence for delivering STOA, a sovereign API and integration platform with an MCP module. The accepted Envoy data-plane decision defines the target: the data plane uses upstream Envoy, configuration comes through STOA Link over xDS, and the MCP module runs behind Envoy. The ADR also lists open implementation details; acceptance of the decision is not evidence that every part has shipped.
Planning cycles and the delivery path
Work is planned in cycles with scoped items and completion tracking. Cycle capacity is evaluated from committed work and observed velocity; the cycle tooling reads the current cycle rather than assuming fixed dates. See the repository's cycle process. A planning cycle is distinct from a component release: the release workflow runs on changes to main and creates releases only when Release Please produces them.
The contribution process requires a defined objective, deliverables and verifiable completion criteria. Changes proceed through a branch and pull request, applicable tests, documentation updates and review. The published contributor guide describes this path. The evidence chain is:
Scoped change → pull request → checks on its revision → merged commit
→ component release/tag → release notes and code comparison
Release automation and the component changelogs provide the last steps of this chain; cycle planning provides context, not proof that a change was released. Sources: release workflow, component changelog.
Non-regression and quality gates
ADR-031 records the reusable CI architecture: setup actions, shared workflows and component orchestrators. For the exact current checks, read the workflow at the revision being assessed; the ADR describes the decision, while executable workflow files determine what runs.
| Evidence | Checks performed |
|---|---|
| Python CI and API orchestrator | Ruff, mypy, pytest and coverage; the API also has integration tests using PostgreSQL. |
| Node CI | Lint, formatting when present, tests (with coverage when requested), and build when enabled by the caller. |
| Rust CI | Formatting, Clippy and tests; coverage and its configured threshold run on main pushes and scheduled runs. These are evidence for the component tested, not proof of Envoy migration completion. |
| Regression Guard | Detects fix pull requests and looks for regression-test changes. The workflow contains explicit exemptions, including documentation/configuration-only fixes and an override label. |
| CI Gate and aggregation script | Detect changed components, run their workflows and aggregate their results. Change detection and security must succeed; selected components must succeed, and unselected components must be skipped. Missing or inconsistent results fail. The gate also checks image pinning. |
A green aggregate is therefore conditional on change detection and the selected workflows; it does not mean every test in the repository ran. Python type checking can be advisory through mypy-enforce; the Node translation-key check is also advisory. Inspect these settings and the job logs when assessing a regression. Sources: Python CI, Node CI, aggregation script.
For a delivery review, retain the tested commit and its check results together. Distinguish applicable builds, tests and ci-gate from downstream deployment or synchronization jobs: they have different scopes in the component orchestrators and CI Gate.
Semantic versions and release cadence
The published release notes document independent semantic versions for control-plane-api, control-plane-ui, portal, stoa-gateway and stoa-go. There is no single shared version for this set of components. The release configuration selects a release strategy per component, separate release pull requests and component-prefixed tags; the manifest stores the tracked versions.
Versions use MAJOR.MINOR.PATCH, with component tags shaped as component-vMAJOR.MINOR.PATCH. The published versioning policy assigns major increments to breaking API changes, minor increments to backward-compatible features, and patch increments to fixes and security patches. Do not infer compatibility from the number alone: review breaking changes and upgrade instructions in the release notes. The configuration explicitly sets bump-minor-pre-major and bump-patch-for-minor-pre-major, so pre-1.0 changes must be interpreted using those settings. Source: release configuration.
The same configuration maps conventional commit types into release-note sections: feat to Features, fix to Bug Fixes, perf to Performance and security to Security. Documentation, maintenance, refactoring, tests and CI sections are hidden. Release notes are consequently a curated view, not a complete commit inventory. Source: release configuration.
No calendar release frequency follows from these files: Release Please reacts to main, whereas planning cycles scope work. A cycle ending does not itself prove that a new component version exists.
Published changelog and architecture decisions
The release notes expose per-component versions, dates and release links. The documentation synchronization workflow runs on a release event, a daily schedule or manual dispatch and proposes a documentation pull request. Its script updates the generated summaries in both English and French from GitHub releases. Publication of a release and merging its documentation update are separate steps.
The ADR index provides the published architectural record. Read each decision's status, amendments and supersession links: ADR-073, for example, supersedes earlier data-plane decisions and amends others. Use an ADR to explain why a change was chosen, and release/commit evidence to establish when it became available.
Tracing changes between two versions
Use the following review procedure, based on the component changelog, release configuration and published release notes:
- Identify the component and the two release tags. For a platform installation, record each component version separately.
- Open the corresponding release entries and the changelog comparison link. The API changelog contains concrete tag-to-tag comparisons and commit links.
- Follow commits and pull requests to inspect the full diff, tests and check results for the relevant revision. Include commit types hidden from release notes.
- Read linked ADRs and migration instructions for the changed behavior; distinguish accepted design, implemented code and released artifacts.
- Record the two tags, comparison link, relevant pull requests/commits, CI evidence and ADR links in the review. This makes the conclusion reproducible without treating a cycle status or an ADR alone as release evidence.
Source revisions
Repository links below are pinned to the inspected revisions. For another release, inspect the same paths at that release's commit.