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

Outline the shared validation model for v0.2.0

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-07 16:37:34 +00:00
parent f55f6331cb
commit a4b1b6d5d2
2 changed files with 170 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
docs/roadmap/model.md Normal file
View File

@@ -0,0 +1,131 @@
# Validation API and profile model
Status: Agreed direction for v0.2.0; detailed API design and implementation
planning remain to be completed.
This roadmap describes the shared model that enables the optional validation
capabilities in the [v0.2.0 roadmap](v0.2.0.md). It owns their common API,
configuration, execution, and diagnostic design. The release roadmap owns each
capability's purpose and scope. A staged implementation plan will follow the
finalized release scope.
## Rationale and current baseline
ReleaseKit v0.1.0 exposes `Check` and `Publish` through the root facade. Both
accept `ReleaseRequest` and use shared candidate-validation machinery. Validation
runs the standard offline Go suite, followed by `AdditionalChecks` when supplied.
Selected executable builds follow validation. The CLI maps profile `checks`
commands to the additional-check callback.
This provides a common procedure and a product-specific extension point. The
request and profile currently have no structured selection for shared optional
validation. Race testing, full vet, package compilation, formatting, and
Markdown checks need a coherent home as they are added.
The model should let consumers declare their choices once while ReleaseKit owns
execution and coordination. This follows [ADR 0002](../adr/0002-routine-releases.md):
shared capabilities should reduce application code and routine developer
decisions. The facade boundaries in [ADR 0001](../adr/0001-public-facade.md)
provide the existing architectural foundation.
## Target end state
### One validation specification
Add a facade-owned `ValidationSpec` to `ReleaseRequest`, with a corresponding
`validation` object in the release profile. Use typed Go fields and ordinary
JSON settings to express the same supported selections. Group related choices,
including base-test and vet settings, so their relationship is clear.
The specification accommodates the agreed race, full-vet, package-compilation,
Go-formatting, and Markdown-link capabilities. Its zero value and an omitted
profile object preserve current default validation. Consumers enable optional
checks according to their product needs.
Go callers and CLI users receive equivalent validation behavior. The CLI owns
profile parsing and presentation; the facade owns the public types and contracts;
internal implementation owns execution. Exact field names and representations
will be settled together during implementation planning.
### Shared coordination
`Check` and `Publish` pass the same specification through one internal validation
path bound to the captured candidate. ReleaseKit constructs the selected Go
commands, manages its shared environment, determines execution order, and
propagates failures and cancellation.
Race selection changes the one base suite invocation. Selecting a separate
full-vet pass automatically omits test-time vet. Package-compilation targets
express compatibility checks independently of executable artifact selection.
Consumers obtain this coordination through their declarations.
Keep the executor straightforward and internal, with ordinary functions for
the selected capabilities. The public model expresses validation choices;
ReleaseKit maintains their execution procedure. Existing candidate rechecks,
offline validation, and source-publication outcomes retain their meaning.
### Clear responsibility boundaries
| Concern | Model owner |
| --- | --- |
| Base tests, full vet, package compilation, formatting, and Markdown links | Shared validation specification |
| Product-specific assertions and example checks | Existing `AdditionalChecks` callback and profile `checks` |
| Expected authoritative push destination | Publication settings and endpoint handling |
| Executable package, binary name, and artifact targets | Build declaration |
| Hosted destination and credentials | Delivery settings |
`AdditionalChecks` and profile `checks` remain available for substantive
consumer behavior. Shared capabilities use the validation specification.
Preserve the current behavior of existing declarations as the new options land.
The expected-endpoint feature remains a publication guard, and `Check` remains
local-only. Selecting package-compilation checks leaves a source-only consumer's
deliverable selection unchanged. Tool installation and dependency preparation
remain separate from offline candidate validation.
### Consistent diagnostics
Shared validation failures identify the check and expose useful details to Go
callers. File-oriented checks provide source locations and actionable findings
where applicable. The CLI presents those details consistently through the
ordinary candidate-check and publication commands.
Use a small facade-owned error model with stable check identity and support for
underlying error causes and cancellation. Preserve `errors.Is` and `errors.As`
behavior across internal conversions and facade wrapping. Exact error types
and diagnostic fields will be selected for the agreed capabilities during API
design.
Validation failures and publication outcomes have distinct meanings. Existing
publication states continue to describe whether publication was attempted,
confirmed, conflicted, or remains uncertain. The model preserves the existing
failure-stopping behavior of the candidate workflow.
## Work needed
- Design the Go validation specification and profile representation together,
covering defaults, related selections, and their mapping to shared execution.
- Consolidate request conversion and validation coordination where needed so
`Check`, `Publish`, and their CLI forms use the same decisions.
- Define check identity, useful diagnostic detail, error wrapping, and CLI
presentation as one small model for the accepted capabilities.
- Preserve the additional-check extension point and the separate publication,
build, and delivery responsibilities while integrating the new specification.
- Update GoDoc, configuration and CLI references, consumer examples, and
internal guidance as the model is implemented. Explain any migration needed
for existing additional commands that become shared selections.
- Verify unchanged default behavior, equivalent API/profile selections, one
base suite execution, coordinated test/vet behavior, and failure/cancellation
propagation. Individual feature work supplies its own behavioral coverage.
## Adoption evidence
Evaluate the design against all three known consumer shapes: Audita's default
validation and executable builds; ConfigKit's selected test, vet, and library
compilation checks; and PromptKit's shared validation plus substantive example
assertions.
Completion should give each consumer a small declaration and the same routine
release operation. The model should support the agreed v0.2.0 capabilities with
shared execution and clear diagnostics while keeping product-specific work in
the existing extension point.