Plan ConfigKit adoption sprint
This commit is contained in:
@@ -1,9 +1,10 @@
|
||||
# ConfigKit v1.1.0 adoption
|
||||
|
||||
Status: recommended adoption scope recorded; implementation has not begun.
|
||||
This roadmap covers the embedded `ckconfig` dependency and source-report
|
||||
migration. [Recommended scope decisions](#recommended-scope-decisions) record
|
||||
the first sprint and the extensions deferred to later work.
|
||||
Status: adoption scope selected; implementation has not begun. This roadmap
|
||||
defines the embedded `ckconfig` dependency and source-report target.
|
||||
[Selected scope decisions](#selected-scope-decisions) distinguish adoption from
|
||||
deferred extensions. The [implementation plan](implementation.md) owns stage
|
||||
order, concrete changes, and validation steps.
|
||||
|
||||
## Purpose and authority
|
||||
|
||||
@@ -19,9 +20,10 @@ This follows the clarified integration goal and the existing
|
||||
[architecture policy](../policy/architecture.md#backend-and-library-integration).
|
||||
The [agent](../policy/agents.md), [testing](../policy/testing.md),
|
||||
[documentation](../policy/documentation.md), [release](../policy/release.md), and
|
||||
[OSS](../policy/oss.md) policies govern implementation. This roadmap proposes
|
||||
work; current contracts remain in GoDoc, the [CLI reference](../cli.md), and the
|
||||
[consumer guide](../consumers/guide.md) until implementation lands.
|
||||
[OSS](../policy/oss.md) policies govern implementation. This roadmap records
|
||||
the selected target; current contracts remain in GoDoc, the
|
||||
[CLI reference](../cli.md), and the [consumer guide](../consumers/guide.md) until
|
||||
implementation lands.
|
||||
|
||||
## Current baseline and review evidence
|
||||
|
||||
@@ -146,12 +148,12 @@ CLI contract when implemented.
|
||||
|
||||
### Deferred inspection expansion
|
||||
|
||||
Metadata inspection and path discovery are recommended as the next functional
|
||||
sprint after adoption (OD-3). Failed-load source inventory, detailed comparison,
|
||||
Metadata inspection and path discovery are the next functional work proposed
|
||||
after adoption (OD-3). Failed-load source inventory, detailed comparison,
|
||||
and structured diagnostics remain separate later proposals (OD-4 through OD-6).
|
||||
The [configuration inspection extensions](deferred.md#configuration-inspection-extensions)
|
||||
record owns their proposed capabilities and design considerations. None is part
|
||||
of this adoption sprint or a new requirement on existing providers.
|
||||
of this adoption scope or a new requirement on existing providers.
|
||||
|
||||
### Consumer migration and module coordination
|
||||
|
||||
@@ -176,7 +178,7 @@ own adapters and composed example. Under OD-1, prepare ckconfig independently
|
||||
first and review ckprompt next. This roadmap does not select an unreviewed
|
||||
PromptKit release or claim a new matched integration set.
|
||||
|
||||
### Interim workspace guidance
|
||||
### Independent module compatibility
|
||||
|
||||
Once local ckconfig uses the vanity ConfigKit types, the usual three-module
|
||||
`go.work` selects it for local ckprompt as well. Until ckprompt migrates, its
|
||||
@@ -184,67 +186,26 @@ old-path ConfigKit inspection and comparison types cannot satisfy the new
|
||||
ckconfig contracts. This is a temporary composition mismatch, even though each
|
||||
module can be validated independently against its own dependencies.
|
||||
|
||||
During that interval, preserve the ignored local workspace and use `GOWORK=off`
|
||||
for dependency preparation, tests, and example runs. From the repository root,
|
||||
with the selected Go 1.27 toolchain on `PATH` and dependencies prepared:
|
||||
During that interval, each module's independent validation uses its own declared
|
||||
dependencies with workspace discovery off. The unchanged ckprompt and composed
|
||||
example retain published ckconfig v0.2.0 and their existing upstream libraries;
|
||||
their success does not establish compatibility with migrated local ckconfig.
|
||||
Development and consumer guidance explain the temporary mismatch. Existing
|
||||
ignored workspace files remain local; restoring aligned workspace composition
|
||||
belongs to the later ckprompt migration.
|
||||
|
||||
```sh
|
||||
GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...
|
||||
(cd integrations/ckconfig && GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...)
|
||||
(cd integrations/ckprompt && GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...)
|
||||
```
|
||||
### Release preparation
|
||||
|
||||
The unchanged ckprompt suite and composed example then use published ckconfig
|
||||
v0.2.0 and their existing upstream dependencies. Their success does not validate
|
||||
composition with the migrated local ckconfig. Keep local replacements and
|
||||
workspace files out of the adoption commit. Resume three-module workspace and
|
||||
composed-consumer validation after ckprompt's migration; update the ignored
|
||||
workspace's Go version as needed for its member modules at that point.
|
||||
The target candidate is ckconfig v0.3.0, with full tag
|
||||
`integrations/ckconfig/v0.3.0`, subject to the existing fresh-version guards.
|
||||
A pre-v1 minor fits the intentional ConfigKit type-identity, consumer-minimum,
|
||||
and report-schema changes. Its checked-in note explains these changes and
|
||||
consumer migration, with the usual immutable licensing footer. Current module
|
||||
notices describe the selected graph and pinned upstream source.
|
||||
|
||||
When the dependency change lands, update the development guide's workspace
|
||||
instructions to explain this interval. Restore the aligned-workspace guidance
|
||||
when ckprompt adopts the new dependencies. Until implementation, the existing
|
||||
development instructions describe the current compatible baseline.
|
||||
|
||||
## Work from the baseline
|
||||
|
||||
1. **Prepare module metadata for the recommended scope.** Follow OD-1 and
|
||||
OD-2; OD-3 through OD-6 remain deferred. Select the
|
||||
Go 1.27 maintainer toolchain, update ckconfig's requirement,
|
||||
imports, and minimum, and regenerate authentic sums with workspace discovery
|
||||
off. Inspect the resulting dependency graph; do not commit local replacements
|
||||
or environment files as an adoption mechanism.
|
||||
2. **Adapt APIs and source reports.** Update the native source field accesses,
|
||||
DTOs, text/YAML output, affected tests, and example code. Add empty-import
|
||||
evidence, including empty lists and record order. Preserve
|
||||
current coordination and outcomes. Adapt upstream results rather than
|
||||
adding domain validation.
|
||||
3. **Update canonical documentation and notices.** Revise the ckconfig README
|
||||
and GoDoc, [CLI source-report reference](../cli.md#list-configuration-sources),
|
||||
consumer guide, release toolchain instructions, and development workspace
|
||||
guidance with the implemented changes. Review the selected graph and
|
||||
upstream notices, then update ckconfig attribution with the vanity identity,
|
||||
selected versions, and pinned source links. Update other module notices only when their actual selections
|
||||
change. Preserve published release history.
|
||||
4. **Validate the selected end state.** Run the ckconfig suite, including its
|
||||
maintained example, independently with `GOWORK=off` and read-only module
|
||||
metadata on the selected Go 1.27 toolchain. Update focused adapter/report
|
||||
assertions for the new vocabulary and faithful projection of returned
|
||||
evidence. Preserve coverage of request forwarding, diagnostics, cancellation,
|
||||
output failures, and supported error identity. Assertions establish
|
||||
CommandKit adaptation; ConfigKit owns tests of its domain correctness.
|
||||
Review changed Markdown links, fragments, and examples. Use the interim
|
||||
workspace guidance for unchanged modules; record that their independent
|
||||
checks do not establish compatibility with the migrated ckconfig. Full
|
||||
composed-workspace validation belongs to the later ckprompt migration.
|
||||
5. **Prepare the integration release.** Propose ckconfig v0.3.0, subject to the
|
||||
existing fresh-version guards, with tag `integrations/ckconfig/v0.3.0`.
|
||||
Explain changed ConfigKit type identity, Go minimum, report fields, and
|
||||
consumer migration in its checked-in note with the usual licensing footer.
|
||||
A pre-v1 minor fits these intentional compatibility changes. Use the existing
|
||||
selected-module release procedure when publication is requested; this plan
|
||||
adds no release gate. Source publication and hosted Gitea delivery retain
|
||||
their separate outcomes.
|
||||
Adoption includes release preparation, not source publication or hosted
|
||||
delivery. The existing [release procedure](../release.md) owns those operations
|
||||
and their separate outcomes when requested; this target adds no release gate.
|
||||
|
||||
## Completion evidence
|
||||
|
||||
@@ -252,34 +213,33 @@ Implementation is complete when ckconfig's actual module metadata and imports
|
||||
select the new dependency, the selected report changes faithfully expose its
|
||||
returned evidence, the module suite and maintained consumer pass independently,
|
||||
and current documentation, notices, and release preparation describe that state.
|
||||
Record final validation evidence and the temporary workspace composition
|
||||
status. OD-3 through OD-6 remain in deferred work; their implementation is not
|
||||
a completion condition for this sprint. A future source release is reported
|
||||
separately from implementation completion; preparing this roadmap does not publish a version
|
||||
or migrate external applications.
|
||||
Completion evidence distinguishes independent module validation from the
|
||||
temporary workspace composition mismatch. OD-3 through OD-6 remain in deferred
|
||||
work; their implementation is not a completion condition for adoption. A future
|
||||
source release is reported separately from implementation completion.
|
||||
|
||||
## Recommended scope decisions
|
||||
## Selected scope decisions
|
||||
|
||||
These dispositions record the review recommendations for the adoption sprint.
|
||||
They define its planned scope, not implemented contracts or authorization to
|
||||
These dispositions record the user's selected adoption scope.
|
||||
They define the target, not implemented contracts or authorization to
|
||||
publish. Deferred features still need focused API and CLI design.
|
||||
|
||||
| Decision | Recommended disposition | Reason |
|
||||
| Decision | Selected disposition | Reason |
|
||||
| --- | --- | --- |
|
||||
| OD-1: Integration sequencing | Implement and prepare ckconfig independently first; review ckprompt next. | Independent releases keep this sprint focused. Document the temporary workspace mismatch and lack of a newly aligned release pair. |
|
||||
| OD-1: Integration sequencing | Implement and prepare ckconfig independently first; review ckprompt next. | Independent releases keep adoption focused. Document the temporary workspace mismatch and lack of a newly aligned release pair. |
|
||||
| OD-2: Empty-import evidence | Include `empty_import_selections`, with `[]` when empty, in text and YAML source reports. | Exposes existing upstream evidence alongside the other report-schema changes. |
|
||||
| OD-3: Metadata and path discovery | Defer to the next functional sprint after adoption. | A coherent optional capability needs its own field/history report and command design. |
|
||||
| OD-3: Metadata and path discovery | Defer to the next functional work after adoption. | A coherent optional capability needs its own field/history report and command design. |
|
||||
| OD-4: Failed-load source inventory | Defer to a separate source-inspection enhancement. | Requires source evidence on error and deliberate report/failure coordination. |
|
||||
| OD-5: Detailed comparison | Defer; retain the existing reduced report in this sprint. | A richer form needs a report-selection and compatibility decision. |
|
||||
| OD-6: Structured diagnostics | Defer; retain native diagnostic rendering in this sprint. | Coordinate machine-readable records with shared reporting and outcome delivery. |
|
||||
| OD-5: Detailed comparison | Defer; retain the existing reduced report during adoption. | A richer form needs a report-selection and compatibility decision. |
|
||||
| OD-6: Structured diagnostics | Defer; retain native diagnostic rendering during adoption. | Coordinate machine-readable records with shared reporting and outcome delivery. |
|
||||
|
||||
The first sprint therefore covers dependency and API migration, source-report
|
||||
Adoption therefore covers dependency and API migration, source-report
|
||||
terminology and empty-import evidence, documentation and notices, independent
|
||||
module validation, and ckconfig release preparation. Core retains its own Go
|
||||
minimum. Application loaders continue to own discovery and loading policy.
|
||||
|
||||
Coordinating both integrations before release remains an alternative if a
|
||||
matched adoption path becomes necessary. It would expand the sprint to include
|
||||
matched adoption path becomes necessary. It would expand the scope to include
|
||||
PromptKit review and ckprompt migration; publication would still proceed in
|
||||
dependency order. The [deferred feature record](deferred.md#configuration-inspection-extensions)
|
||||
retains the capability proposals and unresolved design choices for OD-3 through
|
||||
|
||||
Reference in New Issue
Block a user