diff --git a/docs/roadmap/model.md b/docs/roadmap/model.md new file mode 100644 index 0000000..8c211c3 --- /dev/null +++ b/docs/roadmap/model.md @@ -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. diff --git a/docs/roadmap/v0.2.0.md b/docs/roadmap/v0.2.0.md index 7f1882b..533b411 100644 --- a/docs/roadmap/v0.2.0.md +++ b/docs/roadmap/v0.2.0.md @@ -10,7 +10,39 @@ The priorities in [ADR 0002](../adr/0002-routine-releases.md) guide this work: minimize application-owned release code, duplicated mechanics, and routine developer decisions through a standard, minimal API. -## 1. Use the application's module-selected ReleaseKit version in CI +## 1. Establish the shared validation API and profile model + +### Rationale and current baseline + +ReleaseKit has a shared candidate workflow and a product-specific additional +check extension point. The optional validation capabilities planned for v0.2.0 +need a coherent selection and diagnostic model across the Go API and profile. + +The [validation-model roadmap](model.md) records this enabling work and its +rationale. A common model lets consumers declare choices once and receive +ReleaseKit's shared execution and coordination. + +### Target end state + +A facade-owned validation specification and corresponding profile object +express the agreed optional checks with consistent defaults and behavior. +ReleaseKit owns coordination and diagnostics through the existing `Check` and +`Publish` operations. Product-specific checks, publication expectations, +artifact builds, and delivery retain their distinct responsibilities. + +### Work needed + +- Design and integrate the shared specification, profile mapping, execution, + and error model described in [model.md](model.md). +- Preserve existing default behavior and additional-check support, and align + GoDoc, profile guidance, and CLI reporting as the model lands. +- Evaluate the model against Audita, ConfigKit, and PromptKit before finalizing + the interfaces used by the individual validation features. + +Completion should provide a common foundation for the validation capabilities +below, with small consumer declarations and reusable execution. + +## 2. Use the application's module-selected ReleaseKit version in CI ### Rationale and current baseline @@ -63,7 +95,7 @@ installed tool remain supported use cases. Completion should leave downstream maintainers with one ReleaseKit dependency update for this integration and a maintained template they can adopt directly. -## 2. Select one base test invocation, including race testing +## 3. Select one base test invocation, including race testing ### Rationale and current baseline @@ -100,7 +132,7 @@ unavailable prerequisites clearly and preserves the selected validation. Completion should let ConfigKit and PromptKit select a race-enabled suite once and remove the corresponding consumer-owned test invocation. -## 3. Offer a separate full vet pass +## 4. Offer a separate full vet pass ### Rationale and current baseline @@ -130,7 +162,7 @@ ReleaseKit owns the offline command and its coordination with base testing. Completion should replace ConfigKit's and PromptKit's separate vet commands and manual test-time vet settings with one declarative choice. -## 4. Verify package compilation for selected targets +## 5. Verify package compilation for selected targets ### Rationale and current baseline @@ -165,7 +197,7 @@ separate concern. Consumers select targets for their support commitments. Completion should let ConfigKit declare its two Linux targets and remove its release-specific compilation loop. -## 5. Check an optional expected publication endpoint +## 6. Check an optional expected publication endpoint ### Rationale and current baseline @@ -198,7 +230,7 @@ Consumers that omit the expectation keep the current remote-selection model. Completion should let consumers declare the intended push destination without maintaining their own publication preflight logic. -## 6. Offer Go formatting validation +## 7. Offer Go formatting validation ### Rationale and current baseline @@ -230,7 +262,7 @@ unchanged when the option is unset. Completion should let PromptKit remove its local formatting loop and select the shared check through its release profile. -## 7. Offer offline Markdown-link validation +## 8. Offer offline Markdown-link validation ### Rationale and current baseline