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

Settle the incremental validation API rollout

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-07 18:24:25 +00:00
parent 8c742cd11d
commit 0c7129ab75
2 changed files with 20 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/roadmap/implementation.md
View File

@@ -1,7 +1,6 @@
# Validation model implementation plan
Status: Proposed implementation sequence; the API rollout question below needs
resolution before the stages that expose optional selections.
Status: Ready for implementation using incremental API rollout.
This plan implements the enabling work in [model.md](model.md), guided by
[ADR 0003](../adr/0003-declarative-validation.md). It is written for a Luna
@@ -35,6 +34,16 @@ validation features makes their selections operational.
## Design to carry through the stages
### API rollout
Complete the shared refactor, diagnostics, candidate readers, and conversion
boundaries in this plan first. Introduce each public validation setting with
its functioning capability. The first capability introduces `ValidationSpec`
and the request/profile field; subsequent capabilities add their supported
selections. Go and profile behavior remain equivalent, and each feature owns
its behavioral coverage. The model's full target is reached as the capability
implementations land.
### Validation declarations
The intended complete facade shape is:
@@ -89,10 +98,10 @@ byte counts are nonnegative. Exclusions identify literal repository-relative
file or directory paths; a directory exclusion includes its committed
descendants. Preserve Git path spelling and use slash-separated paths.
These declarations describe the complete intended model. Stage 5 implements
the rollout selected under Open Questions. Public settings acquire operational
behavior with their capability implementations, and current documentation
describes the implemented boundary precisely.
These declarations describe the complete intended model. Public settings
acquire operational behavior with their capability implementations under the
incremental rollout above. Current documentation describes the implemented
boundary precisely.
### Execution and ownership
@@ -256,12 +265,10 @@ syntax, anchors, and selected failure policy.
**Outcome:** The public model has an agreed representation, shared conversion,
and cause-preserving errors across `Check` and `Publish`.
1. Apply the API rollout decision under Open Questions. For the recommended
incremental rollout, implement the public diagnostic types now and retain
1. Implement the public diagnostic types now and retain
the complete specification above as the blueprint for capability stages.
Introduce `ReleaseRequest.Validation`, `ValidationSpec`, and supported
settings with the first capability implementation. This avoids exporting an
empty placeholder or a selection with no implementation.
settings with the first capability implementation in subsequent feature work.
2. Define internal counterparts for the intended settings where required by
actual coordination code. Use explicit field/target conversions through
the same root helper for both operations. Add remaining fields as used.
@@ -359,35 +366,3 @@ and later feature implementation can proceed through the shared model.
5. Commit the completed unit and report its verification, remaining capability
work, and clean or preserved worktree state. The subsequent architecture
review and testing/next-step decisions belong to the user after this sequence.
## Open Questions
### Should the complete optional specification be exported in the enabling sprint?
**Recommendation:** Adopt the complete schema as the design and introduce each
public setting with its functioning capability. Execute the shared refactor,
diagnostics, candidate readers, and conversion boundaries in this plan first.
The first capability then introduces `ValidationSpec` and the request/profile
field; subsequent capabilities add their supported selections. This keeps Go
and profile behavior equivalent, avoids public placeholders and temporary
unsupported-option machinery, and lets each feature own meaningful coverage.
The model's full target is reached as the feature implementations land.
**Viable alternative:** Export the full schema during the enabling sprint and
report an explicitly selected, unimplemented check as unavailable before
validation proceeds. This establishes the complete configuration shape at once
and supports declaration-level integration work. It needs a small temporary
internal availability check and clear current documentation; otherwise an
enabled selection could be silently omitted. Remove each availability guard
when its checker lands. Zero/default declarations continue to work.
**Another viable alternative:** Include all optional validation checker bodies
in this sprint, splitting Markdown parsing and destination/anchor validation
into separate additional stages. This delivers a fully operational specification
at once and avoids transitional API behavior, while broadening this enabling
plan into most of the validation feature work in the release roadmap. It still
leaves CI tooling and the expected publication endpoint as separate work.
Stages 1–4 are independent of this choice. Stages 5–8 describe the recommended
rollout. The choice needs resolution before an implementation agent treats the
public API rollout as settled.