Repository navigation
Spec Development Workflow
Part of the Technical Specification. Requirement prefix: DEV. Makes Development Process and Contributing normative.
Trunk-based development with short-lived branches.
gitGraph
commit id: "main"
branch feat-charging-options
checkout feat-charging-options
commit id: "feat: charging options"
commit id: "test: parity fixtures"
checkout main
merge feat-charging-options id: "squash merge"
branch fix-cursor-expiry
checkout fix-cursor-expiry
commit id: "fix: cursor expiry"
checkout main
merge fix-cursor-expiry id: "squash merge 2"
commit id: "chore: release 1.1.0" tag: "v1.1.0"
| ID | Requirement | Verification |
|---|---|---|
| DEV-001 |
main MUST always be releasable. Work happens on branches named <type>/<issue>-<slug> that live at most a few days; long work is split or hidden behind a feature flag (REL-010). |
Review |
| DEV-002 | Every change MUST arrive by pull request; direct pushes to main are blocked. |
Ops |
| DEV-003 | Pull requests MUST be squash-merged with a title in Conventional Commits 1.0.0 form (feat:, fix:, perf:, refactor:, docs:, test:, build:, ci:, chore:, with ! or a BREAKING CHANGE: footer for a breaking change). |
Lint |
| DEV-004 | A pull request SHOULD stay under 400 changed lines excluding generated files and fixtures; larger ones MUST explain why. | Review |
| ID | Requirement | Verification |
|---|---|---|
| DEV-010 | Every pull request MUST have at least one approving review from a code owner who is not the author; stale approvals are dismissed by new commits. | Ops |
| DEV-011 | Reviewers MUST check: correctness against the cited requirement ids, tests at the right layer, licence and attribution impact, no collection vocabulary or internal names, configuration instead of literals, documentation and changelog. | Review |
| DEV-012 | Security-relevant changes need a second review (SSC-018). Changes to this specification need the owner's approval. | Review |
| DEV-013 | Review comments MUST be resolved before merge; disagreements are settled by the owner, with an ADR when the decision is significant. | Ops |
Formatting, lint, scope lint, configuration lint, type checks (where the language has them), unit and integration tests with the coverage gate, mutation testing on changed domain code, OpenAPI lint and breaking-change diff, executed documentation examples, fuzz smoke, image build and boot smoke, SAST, dependency review, secret scanning. A check that cannot run its input MUST fail, never pass silently.
| ID | Requirement | Verification |
|---|---|---|
| DEV-020 | All checks above MUST be required for merge. | Ops |
| DEV-021 | A check that finds nothing to examine (no files, no tests selected, no document) MUST fail with a message, not report success. | Lint |
An issue is ready for development when:
- it states the user or client question it answers, not the data it exposes;
- it cites the requirement ids it implements or changes, or proposes new ones;
- acceptance criteria are testable and name the test layer;
- licence impact is known (which source families, which use classes);
- dependencies and open decisions are resolved, or the issue is labelled blocked;
- it fits in one pull request or is split.
A change is done when:
- the code, tests, documentation, OpenAPI document and changelog entry are in the same pull request;
- every acceptance criterion has a passing test at the stated layer;
- every required check is green, coverage and mutation targets are met;
- a reviewer has approved;
- the traceability matrix lists the test for each requirement touched;
- nothing in it describes how data is collected or names an internal object;
- for an endpoint, the endpoint Definition of Done (TEST-010) is met.
| ID | Requirement | Verification |
|---|---|---|
| DEV-030 | Work MUST NOT start on an issue that fails the Definition of Ready, and MUST NOT be merged before it meets the Definition of Done. | Review |
| ID | Requirement | Verification |
|---|---|---|
| DEV-040 | Code MUST be formatted by the language's standard formatter, with no configuration debates; lint warnings are errors. | Lint |
| DEV-041 | The dependency direction of the layers (domain ← application ← adapters ← entry point) MUST be enforced by the build (NFR-MAINT-001). | Lint |
| DEV-042 | Errors MUST be values or typed exceptions mapped to problem types at one place; no error MAY be swallowed silently. | Review |
| DEV-043 | Every timeout, limit, size and TTL MUST be a configuration key; literals are refused by a lint with a reasoned allow-list. | Lint |
| DEV-044 | Public names MUST come from the domain vocabulary; storage names MUST stay inside the storage adapter. | Lint |
| DEV-045 | Time MUST be handled as instants in UTC internally; conversion to Europe/Berlin happens only when rendering. Money MUST use decimal types. Geometry MUST use WGS 84. | Review |
| DEV-046 | Logging MUST be structured and go through the redacting logger only. | Lint |
| DEV-047 | Comments explain why, not what; every public function of the domain has a doc comment that cites requirement ids where relevant. | Review |
| DEV-048 | Generated code (typed queries, OpenAPI document, configuration reference) MUST be regenerated in CI; a diff fails the build. | Lint |
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