122 lines
5.9 KiB
Markdown
122 lines
5.9 KiB
Markdown
# Architecture Policy
|
|
|
|
**Base Policy Version:** 1.3
|
|
|
|
**Last Updated**: 2026-10-05
|
|
|
|
**Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/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](../roadmap/releasekit.md) 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:
|
|
|
|
1. Applications delete substantial release infrastructure while retaining clear
|
|
ownership of product-specific checks and compatibility decisions.
|
|
2. 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](../adr/0001-public-facade.md) 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](release.md) 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](agents.md).
|
|
|
|
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](testing.md).
|