Repository navigation
Release Process
How a version of ViaFrei API gets from a merged pull request to a signed, verified image and a release page. The maintainer checklist is in the repository: docs/RELEASING.md. Implemented in milestone 0.2.0 (issue #5). Requirements: Spec: CI/CD and Release and Spec: Compatibility and Versioning.
flowchart TD
PR[Pull request with a Conventional Commit title] --> CI{CI green and reviewed}
CI -->|squash merge| MAIN[Push to main]
MAIN --> RP[release-please opens or updates the release pull request]
RP --> RPR[Release pull request: version.txt, manifest and CHANGELOG section]
RPR -->|a maintainer merges it| DRAFT[release-please writes a draft release, no tag yet]
DRAFT --> TAG[tag job creates the annotated tag vX.Y.Z]
TAG --> REL[release.yml builds amd64 and arm64 and pushes by digest]
REL --> SIGN[cosign signature, SLSA provenance and SBOM attestations]
SIGN --> ASSETS[Assets: openapi.json, the OpenAPI diff, SBOMs and SHA256SUMS]
ASSETS --> PUB[Notes get digest, tags and verify commands, draft published]
PUB --> VER[verify job pulls by digest, checks signature, provenance, checksums and healthz]
VER --> MS{Milestone X.Y.Z has open issues}
MS -->|no| CLOSE[Milestone closed]
MS -->|yes| LIST[Open issues listed in the job summary]
-
Versions come from commit titles.
fix:is a patch;feat:is a minor; a breaking change (!or aBREAKING CHANGE:footer) is a minor before 1.0.0 and a major after. Every 0.x and every candidate is a GitHub pre-release. -
Tags are annotated, never moved, never deleted.
release.ymlrefuses a lightweight or malformed tag. Two live tag rulesets (their JSON is indocs/RELEASING.md) apply. One refuses to create or move av*tag with any suffix (-…,+…), for everyone, with no bypass. The other refuses to move or delete anyv*tag, with repository admins as the only bypass. - The draft comes first. release-please writes a draft release, which creates no tag; the workflow then creates the tag itself, so a tag never exists without the run that publishes it.
- The OpenAPI diff is on every release page, against the previous release, so a breaking change is visible even where the version rules allow it.
-
Images exist for confirmed releases only.
release.ymlrefuses a tag with any suffix, a tag that differs fromversion.txt, and a tag that is not on the commit that setversion.txt(the release commit); a push tomainpublishes no image. GitHub refused two further rules here. A tag-name pattern rule needs an Enterprise plan; the suffix ruleset andrelease.yml's own refusals cover that. A creation restriction would also block release-please's tag, because a personal-account repository cannot list the Actions app as a bypass actor. So review of the release commit and the collaborators' trust are the boundary for who creates a plainvX.Y.Ztag. The image tags areX.Y.Z,X.Yandlatest. - Release candidates publish nothing: no image and no release page. To try one, build it locally from its commit.
| Situation | What happens |
|---|---|
| A release is broken | Rollback by redeploying the previous release's digest; the fix ships as a new patch. No tag is moved. |
A fix cannot wait for main
|
Hotfix branch from the tag; its first reviewed pull request brings the current release.yml from main (a tag push runs the workflow of the tagged commit); the fix lands in a reviewed pull request; another reviewed pull request bumps version.txt and the changelog to the patch version; a maintainer tags that commit; the fix is merged back to main with the manifest updated. |
| A release must be withdrawn |
Yank: the release page is titled [YANKED] with the reason and the replacement; the moving tags are pointed back at a good image; a security reason gets an advisory. The release is never deleted. |
| Item | Used by | Without it |
|---|---|---|
SONAR_TOKEN (repository secret) |
CI SonarCloud analysis | the job fails and names the secret |
SNYK_TOKEN (repository secret) |
dependency scan | the job fails and names the secret |
| "Allow GitHub Actions to create and approve pull requests" | release-please | no release pull request |
| The image package public and linked to the repository | anonymous pulls | pulls need a login |
Before a release pull request is merged, CI must be green on it, including the image, compose, coverage (100 % per package, Testing Strategy) and requirement-report jobs.
See also: Container and Deployment · Development Process · Roadmap
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference