base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Plan CommandKit vanity path migration

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-04 03:37:44 +00:00
parent d7cbaed3ed
commit c8d659dfe5
1 changed files with 134 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

178
docs/roadmap/integration-dependency-alignment.md
View File

@@ -1,4 +1,4 @@
# Integration dependency alignment # Integration dependency alignment and vanity-path migration
Status: proposed release-preparation roadmap. This pass adds documentation only; Status: proposed release-preparation roadmap. This pass adds documentation only;
dependency changes and publication remain future work. dependency changes and publication remain future work.
@@ -6,9 +6,10 @@ dependency changes and publication remain future work.
## Purpose and authority ## Purpose and authority
Align the independently released integrations with the core APIs their current Align the independently released integrations with the core APIs their current
source already uses. Publish compatible module versions in dependency order so source already uses, and migrate all three CommandKit modules to the supplied
each integration builds and validates against its declared, downloaded vanity paths. Publish compatible module versions in dependency order so each
dependencies with workspace discovery off. integration builds and validates against its declared, downloaded dependencies
with workspace discovery off.
The [release procedure](../release.md) owns publication commands and release The [release procedure](../release.md) owns publication commands and release
order. The [release policy](../policy/release.md), order. The [release policy](../policy/release.md),
@@ -20,6 +21,8 @@ and release-preparation scope; it does not change those policies.
## Baseline and investigation evidence ## Baseline and investigation evidence
Reviewed baseline: `289a171e97699ad9aa57ee2cc40bdad1c0b680a9`. Reviewed baseline: `289a171e97699ad9aa57ee2cc40bdad1c0b680a9`.
Vanity-path review baseline: `d7cbaed3ed18bc2909c8144f308e2dfd58ade7ec`.
Module declarations and library source were unchanged between these revisions.
- Both integration module declarations require core v0.2.0. The - Both integration module declarations require core v0.2.0. The
[ckprompt declaration](../../integrations/ckprompt/go.mod) also requires [ckprompt declaration](../../integrations/ckprompt/go.mod) also requires
@@ -55,6 +58,28 @@ The successful cases retained ConfigKit v0.8.0 and PromptKit v0.16.0. These
results isolate the CommandKit dependency alignment needed here; they do not results isolate the CommandKit dependency alignment needed here; they do not
prove that future published versions or their downloaded sums already exist. prove that future published versions or their downloaded sums already exist.
### Verified vanity discovery
The core endpoint at `https://go.maximumdirect.net/commandkit?go-get=1` serves
the mapping to `https://forge.maximumdirect.net/base-layer/commandkit`. Go direct
discovery finds the existing core v0.1.0 and v0.2.0 tags. Fetching v0.2.0 through
the vanity path reaches its source but reports a module-path mismatch because
that release declares `gitea.maximumdirect.net/eric/CommandKit`.
Both integration endpoints now return HTTP 200 with these `go-import` contents:
| Vanity path | VCS | Repository URL | Subdirectory field |
| --- | --- | --- | --- |
| `go.maximumdirect.net/ckconfig` | `git` | `https://forge.maximumdirect.net/base-layer/commandkit` | `integrations/ckconfig` |
| `go.maximumdirect.net/ckprompt` | `git` | `https://forge.maximumdirect.net/base-layer/commandkit` | `integrations/ckprompt` |
Go 1.26.8 direct discovery finds each integration's v0.1.0 tag. Disposable
consumer fetches reach the correct nested `go.mod` and report its old declared
module path, confirming subdirectory routing. Discovery is working; the
existing tags have not migrated. The optional fourth metadata field is
supported from Go 1.25, within the existing Go 1.26.0 consumer minimum; see the
[Go discovery reference](https://go.dev/ref/mod#vcs-find).
## Targeted end state ## Targeted end state
### Compatible independently released modules ### Compatible independently released modules
@@ -62,28 +87,56 @@ prove that future published versions or their downloaded sums already exist.
Use the following proposed next versions, subject to the existing fresh-version Use the following proposed next versions, subject to the existing fresh-version
publication guards: publication guards:
| Module | Next release | Required CommandKit dependencies | Full tag | | Module path | Physical module directory | Next release | Required CommandKit dependencies | Full tag |
| --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| Core | v0.3.0 | None | `v0.3.0` | | `go.maximumdirect.net/commandkit` | `.` | v0.3.0 | None | `v0.3.0` |
| ckconfig | v0.2.0 | Core v0.3.0 | `integrations/ckconfig/v0.2.0` | | `go.maximumdirect.net/ckconfig` | `integrations/ckconfig` | v0.2.0 | `go.maximumdirect.net/commandkit v0.3.0` | `integrations/ckconfig/v0.2.0` |
| ckprompt | v0.2.0 | Core v0.3.0 and ckconfig v0.2.0 | `integrations/ckprompt/v0.2.0` | | `go.maximumdirect.net/ckprompt` | `integrations/ckprompt` | v0.2.0 | `go.maximumdirect.net/commandkit v0.3.0` and `go.maximumdirect.net/ckconfig v0.2.0` | `integrations/ckprompt/v0.2.0` |
Minor integration releases fit the existing pre-1.0 compatibility policy: the Minor integration releases fit the existing pre-1.0 compatibility policy: the
reporting migration changes consumer-facing behavior and adopts a core version reporting migration changes consumer-facing behavior and adopts a core version
with incompatible API changes. Migration notes explain the impact on provider with incompatible API changes. The vanity migration also deliberately changes
results, invocation reporting, and consuming applications. Go module and import identities. Migration notes explain the new imports and
dependency set, provider results, invocation reporting, and application changes.
The three modules retain independent versions and source tags. Their candidates The three modules retain independent versions and source tags. Their candidates
may identify successive commits: core publication need not wait for integration may identify successive commits: core publication need not wait for integration
metadata that depends on that newly published core. Each selected module's metadata that depends on that newly published core. Each selected module's
final release suite runs against its actual declared dependencies. final release suite runs against its actual declared dependencies.
### Module and import identity
Change each module declaration and all CommandKit-owned imports to the matching
new path. Core self-imports, including its `internal` packages, use
`go.maximumdirect.net/commandkit/...`; integration self-imports use
`go.maximumdirect.net/ckconfig/...` or `go.maximumdirect.net/ckprompt/...`.
Cross-module imports and requirements use the complete new paths in the table,
including ckprompt's ckconfig dependency.
Update production files, tests, maintained examples, and any import-path-based
test expectations together. A declared vanity module that still imports the
old core path would select a different Go package identity and can violate
`internal` import rules. The matched new releases compose through one core
identity rather than mixing old-path and new-path CommandKit types.
Keep physical directories, repository URLs, and Git tag prefixes as shown. The
Go subdirectory metadata makes the short integration vanity paths resolve to
the existing layout. The existing release profiles select physical directories;
the migration does not rename those directories or flatten integration tags.
Published old-path versions remain immutable. This scope selects the new paths
for new releases and updates consumer guidance; it makes no new promise of
type interoperability between the two identities and adds no old-path forwarding
module or compatibility layer.
### Retained architecture and scope ### Retained architecture and scope
Keep the current library APIs and integration adapters, Go 1.26.0 consumer Preserve exported declaration shapes and runtime behavior while deliberately
minimum, Go 1.26.8 maintainer toolchain, and root-selected ReleaseKit v0.9.0. changing module/import identities. Retain the integration adapters, Go 1.26.0
The successful diagnostic suites indicate dependency selection is sufficient; consumer minimum, Go 1.26.8 maintainer toolchain, and root-selected ReleaseKit
this work selects no API rollback or compatibility shim for old reporting APIs. v0.9.0. The earlier successful diagnostic suites establish the dependency fix
before renaming; the migrated source still needs its own validation. This work
selects no API rollback or shim for old reporting APIs.
Retain ConfigKit v0.8.0, PromptKit v0.16.0, and other dependency selections Retain ConfigKit v0.8.0, PromptKit v0.16.0, and other dependency selections
unless ordinary tidy changes the resolved graph as a consequence of the unless ordinary tidy changes the resolved graph as a consequence of the
@@ -99,54 +152,89 @@ release validation uses normal downloaded dependencies without that redirection.
## Work needed ## Work needed
### Prepare the module-path migration
Migrate the three module declarations and their owned source/test/example
imports using the mapping above. Update CommandKit dependency keys to the
vanity paths as each published predecessor becomes available. Preserve package
names and aliases unless an actual import-resolution change requires an edit.
Update current installation examples, module-selection guidance, package links,
and dependency descriptions in the README, consumer/developer guidance, and
affected GoDoc. Adjust import-path-aware tests to the new identities while
preserving their existing boundary assertions. Retain repository/source and
license URLs as source-hosting links; they are distinct from Go import paths.
Keep historical release records and review evidence accurate instead of doing a
repository-wide textual replacement of the old names.
Ignored development workspaces or disposable module files can support validation
before predecessor releases are downloadable. Keep that evidence separate from
the independent release graph. The migration may be prepared across all three
modules locally, while source publication and final dependency preparation
still follow core, ckconfig, then ckprompt order.
### Prepare and release core ### Prepare and release core
Review the v0.3.0 draft against changes since the published v0.2.0 tag, including Review the v0.3.0 draft against changes since the published v0.2.0 tag, including
completion, invocation reporting, aliases, and release-tool maintenance. Bring completion, invocation reporting, aliases, and release-tool maintenance. Bring
its summary, migration guidance, and immutable source/licensing links into line its summary, vanity import migration, compatibility guidance, and immutable
with the final candidate and current release procedure. Keep published notes source/licensing links into line with the final candidate and current release
and tags unchanged. procedure. Keep published notes and tags unchanged.
Prepare and commit the intended core candidate on `main`, then use the existing Prepare and commit the core candidate declaring `go.maximumdirect.net/commandkit`
source-publication workflow to publish v0.3.0. Preserve the procedure's required on `main`, then use the existing source-publication workflow to publish v0.3.0.
candidate-commit publication before tag publication. The root suite covers the Preserve the procedure's required candidate-commit publication before tag
root module; the still-pending integration alignment is separate work. publication. The root suite covers the root module; still-pending integration
alignment is separate work.
### Align and release ckconfig ### Align and release ckconfig
After core v0.3.0 is published, update ckconfig's core requirement to that version After core v0.3.0 is published under its new path, prepare ckconfig declaring
and prepare dependencies with workspace discovery off. Tidy its module metadata `go.maximumdirect.net/ckconfig` and requiring
and retain authentic sums from actual downloads. No future checksum or local `go.maximumdirect.net/commandkit v0.3.0`. Remove the superseded old core
replacement substitutes for the published dependency. requirement, prepare dependencies with workspace discovery off, and tidy the
module metadata. Retain authentic sums from actual downloads. No future
checksum or local replacement substitutes for the published dependency.
Prepare `integrations/ckconfig/docs/releases/v0.2.0.md`, documenting the new core Prepare `integrations/ckconfig/docs/releases/v0.2.0.md`, documenting the new core
requirement and reporting/completion behavior relevant to consumers. Update requirement, vanity import migration, and reporting/completion behavior. Update
affected current guidance and module-local attribution from the actual resolved affected current guidance and module-local attribution from the actual resolved
graph, including immutable notice links. Validate and publish the selected graph, including immutable notice links. Validate and publish the selected
ckconfig candidate through the ordinary module release workflow. ckconfig candidate through the ordinary module release workflow.
### Align and release ckprompt ### Align and release ckprompt
After ckconfig v0.2.0 is published, update ckprompt's direct requirements to core After ckconfig v0.2.0 is published under its new path, prepare ckprompt declaring
v0.3.0 and ckconfig v0.2.0 together. Prepare downloaded dependencies and tidy `go.maximumdirect.net/ckprompt` and requiring
with workspace discovery off. Retain real sums and inspect indirect changes. `go.maximumdirect.net/commandkit v0.3.0` and
`go.maximumdirect.net/ckconfig v0.2.0` together. Remove the superseded old
CommandKit dependency keys. Prepare downloaded dependencies and tidy with
workspace discovery off. Retain real sums and inspect indirect changes.
Prepare `integrations/ckprompt/docs/releases/v0.2.0.md`, covering the compatible Prepare `integrations/ckprompt/docs/releases/v0.2.0.md`, covering the compatible
dependency set and consumer migration. Align current guidance and module-local dependency set, vanity imports, and consumer migration. Align current guidance
attribution with that selection. Validate and publish its candidate through the and module-local attribution with that selection. Validate and publish its
ordinary module release workflow. candidate through the ordinary module release workflow.
### Record the aligned result ### Record the aligned result
Record the selected versions, candidate revisions, validation outcomes, and Record the selected module paths and versions, candidate revisions, validation
source-publication outcomes separately for all three modules. Update current outcomes, and source-publication outcomes separately for all three modules.
dependency-readiness statements that still describe this mismatch as unresolved; Update current dependency-readiness statements that still describe this mismatch
preserve historical baseline failures in completed review and implementation as unresolved; preserve historical baseline failures in completed review and
records. Link future implementation tracking here without restarting the implementation records. Link future implementation tracking here without
completed ReleaseKit adoption or remediation work. restarting the completed ReleaseKit adoption or remediation work.
## Validation and completion boundaries ## Validation and completion boundaries
Review current CommandKit-owned source and dependency selections for stale
self-imports or old direct dependency keys. Historical notes, source URLs, and
unrelated upstream module identities are outside that mechanical rename.
Confirm release identity still pairs each new module path with its existing
physical directory and tag prefix. The verified redirects are preparation
evidence; publishing the renamed modules is needed for real consumers to use
them through those paths.
Use the selected module's ordinary deterministic offline suite with Use the selected module's ordinary deterministic offline suite with
`GOWORK=off` and read-only metadata after dependency preparation. Its maintained `GOWORK=off` and read-only metadata after dependency preparation. Its maintained
consumer compiles and runs with that suite. ReleaseKit's publication command consumer compiles and runs with that suite. ReleaseKit's publication command
@@ -161,8 +249,10 @@ or ambiguous publication using the existing policy and upstream recovery flow.
Hosted Gitea delivery keeps its separate outcome; this roadmap adds no CI Hosted Gitea delivery keeps its separate outcome; this roadmap adds no CI
polling, live provider calls, or additional publication gate. polling, live provider calls, or additional publication gate.
Alignment is complete when the matched source versions are published, each Alignment is complete when the matched source versions are published under all
integration declares the compatible versions with authentic downloaded sums, three vanity module paths, owned imports and examples use the new identities,
each final selected-module suite passes without workspace or replacement each integration declares the compatible vanity-path versions with authentic
redirection, and its current documentation and attribution agree with that downloaded sums, each final selected-module suite passes without workspace or
graph. Temporary local-source success alone does not establish that end state. replacement redirection, and current documentation and attribution agree with
that graph. Temporary local-source success alone does not establish that end
state.