122 lines
5.9 KiB
Markdown
122 lines
5.9 KiB
Markdown
# Architecture Policy
|
|
|
|
**Base Policy Version:** 1.3
|
|
|
|
**Last Updated**: 2026-10-06
|
|
|
|
**Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
|
|
|
|
## Purpose And Ownership
|
|
|
|
ReleaseKit is 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.
|
|
|
|
The [internal documentation](../internal/overview.md) owns concrete package
|
|
inventory and implementation mechanics. Canonical public contracts own exact
|
|
behavior; ADRs record decision rationale.
|
|
|
|
## Adopted Constraints And Implemented Structure
|
|
|
|
Architectural constraints govern current and future development and reflect
|
|
deliberately selected requirements and decisions. Current architecture describes
|
|
implemented structure. Roadmaps record proposals, implementation status, and
|
|
sequencing; ADRs record significant decisions and rationale. Internal
|
|
implementation choices evolve within these constraints.
|
|
|
|
## 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 available independently of consumer
|
|
checkouts. Committed module and workspace configuration supports independent
|
|
builds; temporary local development configuration remains local.
|
|
|
|
## 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.
|
|
|
|
## Runtime Version Boundary
|
|
|
|
The `buildinfo` public API exposes 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. Go
|
|
declarations and GoDoc define supported consumer API contracts;
|
|
[consumer guides](../consumers/) explain their use, and
|
|
[integration guides](../integrations/) define external formats and protocols.
|
|
The product roadmap records planned capabilities and implementation status.
|
|
|
|
## Trust Boundaries And Threat Scope
|
|
|
|
Base defenses and guarantees on selected requirements. Candidate validation,
|
|
remote-state changes, transport failures, and partial delivery receive explicit
|
|
handling. Additional threat scenarios require a deliberate scope decision under
|
|
the [agent policy](agents.md).
|
|
|
|
Public API, [configuration](../config.md), and integration contracts own
|
|
credential supply and observable handling. Internal documents own the mechanisms.
|
|
Tests use local collaborators and controlled failures as specified by the
|
|
[testing policy](testing.md).
|