5.9 KiB
Architecture Policy
Base Policy Version: 1.3
Last Updated: 2026-10-05
Upstream Source: architecture.md
Purpose And Ownership
ReleaseKit is being designed as an opinionated Go library and release executable for common publication, builds, version injection, and delivery. This policy owns responsibility boundaries, dependency direction, and adopted constraints for development. The product roadmap owns proposed capabilities, implementation status, and sequencing.
Describe concrete package inventory and implementation mechanics in internal documentation when those packages exist. Link to canonical public contracts for exact behavior and to ADRs for decision rationale.
Adopted Constraints And Implemented Structure
Architectural constraints govern current and future development. Record implemented structure accurately, proposals and implementation status in the roadmap, and significant decisions and rationale in ADRs. Describe a target structure as implemented when its changes land.
Constraints must reflect deliberately selected requirements and decisions. Do not promote incidental implementation choices into architectural invariants.
Success Criteria
Evaluate ReleaseKit development and adoption against both criteria:
- Applications delete substantial release infrastructure while retaining clear ownership of product-specific checks and compatibility decisions.
- Consumers adopt one coherent set of deliberately selected release conventions.
Consumer implementations supply evidence of needs. ReleaseKit selects a common model and enough flexibility to express genuine product requirements. API designs should demonstrate reduced consumer infrastructure and consistent conventions through representative consumers.
Responsibility Boundaries
ReleaseKit owns the mechanics of selected publication, version injection, cross-build, and delivery conventions. Applications supply product identity, their main package, selected build targets, application-specific candidate checks, and delivery declarations. Applications own their compatibility decisions and adaptation of version output to the supported runtime accessor.
The release executable invokes the supported orchestration facade and owns argument parsing, output, and exit codes. Library operations return meaningful errors and outcomes, including partial progress and uncertain publication state. Consumers map those values to their own user interfaces.
ReleaseKit builds and tests independently of consuming repositories. Production dependencies use supported public contracts; consumer-private packages and local checkout paths remain outside its dependency graph. Temporary local development configuration stays outside committed module and workspace state.
Public Facades And Dependency Direction
ADR 0001 records the accepted decision for the root
releasekit orchestration facade and separate buildinfo runtime facade.
Both belong to one Go module and share its versioning and compatibility
obligations. Each facade exposes a cohesive consumer contract.
Public named types belong to their facade. Exported signatures, fields, callbacks, and method sets use facade-owned types and deliberately selected public dependencies. Handles retain private implementation state, with explicit forwarding and conversions preserving supported identity, ownership, error semantics, and callback lifetime.
Implementation packages live under Go's internal/ boundary. Dependencies run
from facades into internal implementation; internal production packages depend
on internal contracts. Git operations, Go toolchain execution, Gitea integration,
and orchestration bookkeeping belong behind that boundary. Additional public
packages and extension interfaces require a deliberate decision grounded in a
durable consumer need.
Go declarations and GoDoc own exact API contracts. Compiled-export checks, dependency checks, and external-package behavioral tests protect the selected facade boundaries as implementation lands.
Runtime Version Boundary
The buildinfo public API exposes only runtime information justified by
consumer needs. Its implementation uses the standard library and a small
internal dependency graph independent of release orchestration. Applications
read their embedded version through its supported accessor.
The builder and runtime implementation own the linker symbol and injection mechanism together. Dependency checks protect the runtime boundary; build-and-run integration tests verify that the builder injects the selected version and the public accessor reports it correctly.
External Effects
Keep Git, filesystem, Go toolchain, and Gitea effects behind proportionate internal boundaries and perform them through explicit operations. Select interfaces and package layout for actual responsibilities and testability. The library owns reusable outcomes and failure handling; the executable owns presentation and process exits.
Source publication and asynchronous delivery have distinct outcomes. The release policy governs releases of ReleaseKit itself. Consumer release capabilities and their implementation remain in the product roadmap until supported contracts exist.
Trust Boundaries And Threat Scope
Base defenses and guarantees on selected requirements. Candidate validation, remote-state changes, transport failures, and partial delivery require explicit handling when those operations are implemented. Additional threat scenarios require a deliberate scope decision under the agent policy.
Credential supply and runtime handling belong in the applicable public or integration contracts when implemented. Internal documents own the mechanisms. Tests use local collaborators and controlled failures as specified by the testing policy.