77 lines
3.6 KiB
Markdown
77 lines
3.6 KiB
Markdown
# ADR 0003: Declare optional validation through a shared specification
|
|
|
|
## Status
|
|
|
|
Accepted.
|
|
|
|
## Date
|
|
|
|
2026-10-07
|
|
|
|
## Context
|
|
|
|
Consumers have different release-validation needs. Their additional checks
|
|
include reusable mechanics such as formatting inspection and Go toolchain
|
|
invocations, alongside assertions about product behavior. Maintaining the
|
|
reusable mechanics in each application duplicates code and coordination work.
|
|
|
|
[ADR 0001](0001-public-facade.md) establishes facade ownership of public
|
|
contracts. [ADR 0002](0002-routine-releases.md) prioritizes routine releases
|
|
with little application-owned code or recurring developer effort. Optional
|
|
validation needs a common selection and execution model that supports these
|
|
decisions as shared capabilities grow.
|
|
|
|
## Decision
|
|
|
|
Consumers select shared validation through a typed, facade-owned specification
|
|
and equivalent release-profile settings. Related settings belong together.
|
|
Omitted optional settings preserve existing default validation behavior.
|
|
|
|
`Check` and `Publish` use one internal validation path bound to the captured
|
|
candidate. ReleaseKit owns execution, ordering, coordination between selected
|
|
checks, and propagation of failures and cancellation. The CLI maps profile
|
|
settings to the facade and owns presentation.
|
|
|
|
Shared validation exposes consistent diagnostics through facade-owned errors.
|
|
Findings identify the check and provide actionable detail where applicable.
|
|
Error wrapping preserves underlying causes and cancellation semantics.
|
|
Validation failures and publication outcomes retain their distinct meanings.
|
|
|
|
The existing `AdditionalChecks` callback and profile `checks` support
|
|
product-specific assertions. Publication guards, artifact builds, and delivery
|
|
retain their separate configuration and responsibilities. Validation execution
|
|
and coordination remain internal implementation responsibilities.
|
|
|
|
Evaluate optional capabilities by the application maintenance they remove,
|
|
their clarity of scope, configuration burden, and maintenance cost. A
|
|
capability can serve a small subset of consumers when those benefits justify
|
|
shared support. Consumers select the checks appropriate to their products.
|
|
|
|
GoDoc owns exact public API contracts, and the configuration reference owns
|
|
profile settings. Roadmaps own feature scope and implementation sequencing.
|
|
|
|
## Alternatives considered
|
|
|
|
- Consumer-owned commands preserve local control and leave applications
|
|
maintaining reusable inspection, invocation, and coordination code.
|
|
- Independently configured check and publication paths allow separate
|
|
validation choices and require consumers to keep those choices aligned.
|
|
- A public validator-registration framework supports custom composition and
|
|
expands the public lifecycle and ordering contracts. The existing
|
|
additional-check extension point supports current product-specific needs.
|
|
|
|
## Consequences
|
|
|
|
Applications can replace repeated release mechanics with small declarations.
|
|
Go callers and CLI users receive equivalent selected validation through the
|
|
same release operations. Existing consumers retain their default behavior and
|
|
additional-check integration as optional capabilities are introduced.
|
|
|
|
ReleaseKit assumes responsibility for maintaining shared checks, coordinating
|
|
their interactions, and presenting useful diagnostics. Public selections and
|
|
error contracts carry compatibility obligations. Verification must cover
|
|
default behavior, equivalent API and profile selections, and failure propagation.
|
|
|
|
Internal execution can evolve within the facade boundaries. Each new capability
|
|
requires a clear scope and evidence that shared ownership reduces consumer work.
|