Plan ConfigKit 1.1 adoption
This commit is contained in:
205
docs/roadmap/configkit-v1.1.0.md
Normal file
205
docs/roadmap/configkit-v1.1.0.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# ConfigKit v1.1.0 adoption
|
||||
|
||||
Status: proposed; dependency and report changes are not implemented. This
|
||||
roadmap covers the embedded `ckconfig` integration. Release coordination and
|
||||
additional source evidence have recommendations under [Open Decisions](#open-decisions).
|
||||
|
||||
## Purpose and authority
|
||||
|
||||
Adopt `go.maximumdirect.net/configkit v1.1.0` and expose its capabilities through
|
||||
CommandKit's existing configuration commands in a neutral, consistent way.
|
||||
ConfigKit owns configuration loading, composition, resolution, inspection, and
|
||||
their semantics. CommandKit owns command selection, coordination, presentation,
|
||||
and invocation outcomes. Adapt upstream capabilities faithfully, using current
|
||||
upstream terminology, without adding independent guarantees or commentary
|
||||
qualifying upstream limitations.
|
||||
|
||||
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.
|
||||
|
||||
## Current baseline and review evidence
|
||||
|
||||
Reviewed CommandKit revision: `60841227b7e2928d3fefd3326f0e3f4694f41e6d`.
|
||||
The completed [dependency alignment roadmap](integration-dependency-alignment.md)
|
||||
records the preceding vanity migration and releases.
|
||||
|
||||
| Component | Current selection |
|
||||
| --- | --- |
|
||||
| Core | `go.maximumdirect.net/commandkit v0.3.0`; Go 1.26.0 minimum |
|
||||
| ckconfig | `go.maximumdirect.net/ckconfig v0.2.0`; Go 1.26.0 minimum |
|
||||
| ckconfig dependencies | Core v0.3.0, `gitea.maximumdirect.net/eric/ConfigKit v0.8.0`, YAML v4.0.0-rc.6 |
|
||||
| ckprompt | v0.2.0; ckconfig v0.2.0, old-path ConfigKit v0.8.0 and PromptKit v0.16.0; Go 1.26.0 minimum |
|
||||
| Maintainer release toolchain | Go 1.26.8, with `GOTOOLCHAIN=local` |
|
||||
|
||||
The ConfigKit vanity endpoint and direct Go module discovery resolve v1.1.0 to
|
||||
published commit `191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9`. Its module declares
|
||||
Go 1.27.0 and retains the YAML dependency and LGPL-3.0-or-later library grant.
|
||||
The upstream [v1.0 migration notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.0.0.md)
|
||||
and [v1.1 release notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.1.0.md)
|
||||
describe the adopted API and behavior changes. Upgrading from v0.8.0 also crosses
|
||||
the import, collection, CLI-assignment, and discovery changes documented in the
|
||||
[v0.9 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.9.0.md)
|
||||
and [v0.10 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.10.0.md).
|
||||
|
||||
A disposable ckconfig copy passed its complete module suite and maintained
|
||||
simple example tests on Go 1.27.0 after changing the dependency/import path,
|
||||
minimum, two source-reader fields, and affected test APIs. This establishes that
|
||||
the existing adapter structure remains suitable. It did not exercise the
|
||||
proposed report-field renames, additional source evidence, or a migrated
|
||||
ckprompt; final implementation still needs validation of those selected changes.
|
||||
|
||||
## Targeted end state
|
||||
|
||||
### Dependency and toolchain
|
||||
|
||||
The [ckconfig module](../../integrations/ckconfig/go.mod) requires
|
||||
`go.maximumdirect.net/configkit v1.1.0`, and its production code, tests, and
|
||||
maintained example use that import identity. Raise its consumer minimum to
|
||||
Go 1.27.0. Retain its core v0.3.0 requirement unless implementation identifies
|
||||
a concrete need for a newer core API. Core remains independent of ConfigKit
|
||||
and retains its own Go minimum.
|
||||
|
||||
Use a Go 1.27 toolchain for ckconfig dependency preparation and validation.
|
||||
Update the [maintainer procedure](../release.md#release-toolchain) to select an
|
||||
available Go 1.27 release and distinguish the per-module consumer minimums.
|
||||
The existing host-native, workspace-off launcher can use that toolchain without
|
||||
a new toolchain-selection mechanism.
|
||||
|
||||
### Faithful adaptation and reports
|
||||
|
||||
Retain the existing scope, loader, comparison, diagnostic, and reporting
|
||||
structure. Continue using ConfigKit's public results, native rendering, and
|
||||
diff APIs rather than reproducing its domain logic locally. New collection,
|
||||
discovery, and resolution features can be used by application loaders through
|
||||
the adopted library; they do not inherently require additional CLI flags or
|
||||
CommandKit-owned loading policy.
|
||||
|
||||
Align the existing source report with ConfigKit's current vocabulary:
|
||||
|
||||
| Current API or report spelling | Target |
|
||||
| --- | --- |
|
||||
| `SourceInfo.DestinationUnresolved` | `SourceInfo.DestinationIsFallback` |
|
||||
| `SourceInfo.VersionCheck` / `SourceVersionCheck` | `SourceInfo.VersionEvidence` / `SourceVersionEvidence` |
|
||||
| Text/YAML `destination_unresolved` | `destination_is_fallback` |
|
||||
| Text/YAML `version_check` | `version_evidence` |
|
||||
| Native main layer value `base` | Native main layer value `main` |
|
||||
|
||||
Update DTOs and both report formats together. Preserve the upstream evidence
|
||||
and its supported presence, null, location, ordering, and redaction information
|
||||
through adaptation. Use the upstream terms directly in help and documentation;
|
||||
link to the owning inspection contract for their semantics. Describe the report
|
||||
migration plainly in the release note. The target uses the new field names
|
||||
without duplicate legacy report fields.
|
||||
|
||||
ConfigKit's source inventory also supplies `EmptyImportSelections`, with
|
||||
declaration path, location, and selector. OD-2 addresses including this evidence
|
||||
in the existing source report; it is not yet a selected report-schema addition.
|
||||
|
||||
### Consumer migration and module coordination
|
||||
|
||||
Public ckconfig signatures expose ConfigKit types, so switching import identity
|
||||
requires consumers to migrate the ConfigKit values they pass across those
|
||||
boundaries. Use the adopted upstream API names in maintained consumers and
|
||||
fixtures. Known test changes include `Definition.Secret` to `Sensitive` and
|
||||
`Resolution.Record(..., ChangeNormalization, ...)` to `RecordNormalization`.
|
||||
Review other removed pre-v1 symbols where actually used.
|
||||
|
||||
Migration guidance should link to upstream for source-root `configkit` controls
|
||||
becoming `config`, `optional` becoming `required` with changed defaults,
|
||||
identified-collection registrations and operations, and CLI-assignment ordering.
|
||||
Change affected maintained fixtures when present. Application configuration and
|
||||
validation choices remain application-owned; CommandKit does not introduce a
|
||||
compatibility loader or impose new configuration restrictions.
|
||||
|
||||
ckprompt's current ConfigKit types come from the old package identity. It cannot
|
||||
simply select the new ckconfig release while retaining that wiring. Its later
|
||||
adoption needs a coordinated ConfigKit/PromptKit migration and review of its
|
||||
own adapters and composed example. OD-1 determines scheduling; this roadmap does
|
||||
not select an unreviewed PromptKit release or claim a new matched integration set.
|
||||
|
||||
## Work from the baseline
|
||||
|
||||
1. **Confirm scope choices and prepare module metadata.** Resolve OD-1 and
|
||||
OD-2, 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. Apply the selected
|
||||
empty-import-evidence choice. Retain the existing coordination and outcome
|
||||
behavior, adapting 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, and release toolchain instructions 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. If coordinated
|
||||
ckprompt work is selected, also validate that module and the composed consumer
|
||||
against the proposed dependency set; local-workspace success alone does not
|
||||
establish independent module compatibility.
|
||||
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.
|
||||
|
||||
## Completion evidence
|
||||
|
||||
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 the resolved scope choices and final validation evidence. A future source
|
||||
release is reported separately from implementation completion; preparing this
|
||||
roadmap does not publish a version or migrate external applications.
|
||||
|
||||
## Open Decisions
|
||||
|
||||
### OD-1: Release ckconfig first or coordinate both integrations?
|
||||
|
||||
**Recommendation:** implement and release ckconfig independently first, and
|
||||
review ckprompt's upstream migration as the next integration task. This keeps
|
||||
the current scope concrete and uses the established independent module releases.
|
||||
Existing ckprompt v0.2.0 consumers retain their published dependency set; document
|
||||
that moving them to the new ckconfig needs the corresponding ckprompt migration.
|
||||
The tradeoff is an interval with no newly aligned release pair.
|
||||
|
||||
**Viable alternative:** complete the ConfigKit/PromptKit review and both
|
||||
integration migrations before releasing the next pair, publishing ckconfig first
|
||||
in dependency order. This gives composed consumers a coordinated adoption path
|
||||
and validates the shared type boundaries together. It expands this work into
|
||||
PromptKit adoption and delays ckconfig availability while that review and
|
||||
implementation proceed. No simultaneous tag publication is needed.
|
||||
|
||||
### OD-2: Include empty-import-selection evidence in this adoption?
|
||||
|
||||
**Recommendation:** add `empty_import_selections` to the existing text/YAML
|
||||
source report, projecting ConfigKit's declaration path, location, selector, and
|
||||
record order. This exposes structured source evidence already available
|
||||
upstream without a new command or a second explanation engine. It adds report
|
||||
mapping and focused projection coverage alongside the other schema changes;
|
||||
the exact empty-list presentation should be settled with the implemented report.
|
||||
|
||||
**Viable alternative:** limit this release to migrating the evidence already
|
||||
reported, and defer this additive field to a later inspection enhancement. That
|
||||
reduces the immediate report change and test scope, and still makes the native
|
||||
metadata available to Go consumers of ConfigKit. CLI consumers would continue
|
||||
to lack this upstream evidence, and a later release would need another report
|
||||
and documentation update.
|
||||
Reference in New Issue
Block a user