diff --git a/docs/adr/0003-declarative-validation.md b/docs/adr/0003-declarative-validation.md new file mode 100644 index 0000000..20c702c --- /dev/null +++ b/docs/adr/0003-declarative-validation.md @@ -0,0 +1,76 @@ +# 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.