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