eric/ReleaseKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Adopt shared policies and align ReleaseKit documentation and licensing

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-05 14:39:49 +00:00
parent 4f914f10cf
commit 43c20b0f61
18 changed files with 2540 additions and 528 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
docs/policy/architecture.md Normal file
View File

@@ -0,0 +1,121 @@
# 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).