releasekit/docs/roadmap/migration.md

Roadmap: migrate to the ReleaseKit vanity module path

Status: implementation complete; offline verification and completion review passed.

Objective

Adopt go.maximumdirect.net/releasekit as ReleaseKit's module identifier through a direct migration of the existing code, examples, and consumer guidance. Prepare the change for v0.5.0, with migration instructions for existing consumers. The release policy governs version selection and compatibility.

Baseline at start of migration

The baseline is v0.4.2, commit 7d033c5ca1c95aec7db9690293638a0a1ac887b8.

• go.mod declares gitea.maximumdirect.net/eric/ReleaseKit, with a Go 1.26.0 minimum.
• Production imports, test imports, generated consumer modules, synthetic module proxies, tool bootstrap scripts, and current guidance use that identifier.
• The version-injection linker symbol and compiled API checker also embed the module path.
• Local origin points to ssh://git@forge.maximumdirect.net:22222/base-layer/releasekit.git. The delivery profile and maintainer runbook still identify the older Gitea host and repository location.

The Gitea service now uses forge.maximumdirect.net, replacing gitea.maximumdirect.net. The hostname uses the generic term "forge" for a software hosting service; the software remains Gitea.

Vanity-path readiness evidence

The initial assessment used Go 1.26.10, disposable consumer modules, and isolated module caches. These observations describe the service at assessment time.

Check	Result
HTTPS discovery for the module root, buildinfo, and cmd/releasekit	HTTP 200 with matching go-import metadata.
Repository mapping	https://forge.maximumdirect.net/base-layer/releasekit.
Direct Go version discovery	Listed v0.1.0 through v0.4.2.
Direct download of v0.4.2 through the vanity path	Succeeded and identified the baseline commit.
Download through proxy.golang.org, with sum.golang.org verification enabled	Succeeded.
go get go.maximumdirect.net/releasekit@v0.4.2	Rejected because that tag's go.mod declares the old module path.

Discovery and archive delivery are operational. Consumer adoption requires a new release whose module declaration and package imports use the vanity path. Go defines the module path as the canonical prefix for its package paths; see the Go Modules Reference.

Targeted end state

• The root module declares go.maximumdirect.net/releasekit.
• The existing orchestration and runtime facades are available at go.maximumdirect.net/releasekit and go.maximumdirect.net/releasekit/buildinfo, preserving their current roles and behavior under the architecture policy.
• The CLI package is go.maximumdirect.net/releasekit/cmd/releasekit.
• Version injection, API checks, consumer fixtures, and maintained workflows operate with the new module identity.
• ReleaseKit's hosted release pages use Gitea at forge.maximumdirect.net, owner base-layer, repository releasekit, matching the existing Git remote and vanity mapping.
• Current adoption guidance explains coordinated import, dependency, tool, and workflow updates. The Go consumer minimum remains 1.26.0.
• v0.5.0 introduces the new identity with release notes explaining the migration. Existing published versions retain their original source and module identity.

The implementation uses a direct cutover supported by documented consumer migration steps.

Work required

1. Migrate source and embedded identities

• Update the root module declaration and imports throughout production code and tests, including both public facades and the CLI.
• Update InjectedVersionLinkerSymbol in injection.go to address the runtime implementation under the new path. Keep the builder and runtime accessor aligned through their existing integration coverage.
• Update the module identifier in the compiled API checker, retaining its existing checks for facade ownership and dependency direction.
• Review dependency metadata after the edits and retain the existing Go minimum.

2. Adapt fixtures and maintained examples

• Update generated go.mod files, replacement directives, synthetic proxy metadata, generated Go source, and assertions that refer to ReleaseKit's module identity. Keep each synthetic version's declaration, imports, and archive layout consistent.
• Update the module selected by the tag-delivery workflow, multi-module workflow, and multi-module launcher.
• Update example imports and tool declarations, including local-source verification instructions. Preserve the existing behaviors around tagged tool selection, annotated tag events, module selection, and delivery retries.
• Review remaining old-path occurrences in context. Historical release records and fixtures representing historical source may legitimately identify the original module.

3. Document adoption and prepare release guidance

• Update the README, consumer guides, internal module inventory, and maintained installation and bootstrap examples in their canonical locations.
• Explain how API consumers update imports for both facades and select the new module version. Explain how CLI consumers update tool declarations and copied workflow module identifiers together with dependency selection.
• Explain that packages imported through different module paths have distinct Go identities. Consumers exchanging ReleaseKit facade types should coordinate the corresponding import updates. Use go mod tidy to remove unused requirements and review any old-path dependencies retained transitively.
• Explain that retries of existing consumer tags use their recorded source, tool selection, and matching workflows. Supply migration instructions for new consumer revisions while preserving published tags.
• Prepare docs/releases/v0.5.0.md with the compatibility impact, upgrade steps, and licensing footer required by the release procedure. Select an unused version during release preparation if v0.5.0 has become occupied.
• Update ReleaseKit's delivery profile, maintainer runbook, related fixture expectations, and current hosting links for Gitea at forge.maximumdirect.net/base-layer/releasekit. The vanity path names Go packages; repository URLs address Git transport, source navigation, and hosted release pages. Preserve historical release records and their source URLs.

4. Verify the migration

Use the existing testing policy and development guide to select sufficient coverage.

• Run the complete offline Go suite and compiled API/dependency checks against the migrated candidate.
• Exercise the root facade, buildinfo, and CLI through disposable consumers using the migrated checkout. Reuse existing fixtures where they cover these behaviors, including a built executable reporting the injected version.
• Use the existing executable-workflow coverage to verify tool selection and delivery with the new identity. Focused runs can support development; the complete suite supplies final candidate coverage. Keep synthetic module downloads isolated as described in the development guide.
• Review current documentation, example commands, and remaining old-path references for consistency with their intended source or release.

Live discovery and download checks belong to migration diagnostics outside the deterministic default suite. After publication, a fresh consumer can confirm adoption through the vanity path and public proxy, including the CLI tool path. That confirmation is separate from the source-release completion point.

Completion and publication

Implementation is complete when the new module identity is consistent across source, embedded identifiers, maintained examples, and current guidance, with the relevant offline checks passing and migration release documentation ready.

Publication follows the existing release procedure. Reuse successful validation where it applies to the exact candidate, as allowed by the release policy. Track source publication and hosted-page delivery separately under that procedure.

Completion review

Implementation is committed in 3b803d5. Verification used Go 1.26.10 on linux/amd64 with local toolchain selection. The following work is complete:

Work	Completion evidence
Source and embedded identities	Module declaration, imports, version-injection symbol, and API checker use the vanity path; compiled API/dependency checks passed.
Fixtures and examples	Generated consumer modules, synthetic proxies, launchers, and workflows use the vanity identity; the full offline suite passed, including executable-workflow and tagged-retry coverage.
Adoption and release guidance	Current guides and examples describe the new paths; docs/releases/v0.5.0.md records compatibility impact, migration steps, and the immutable-tag licensing footer.
Gitea hosting references	Delivery profile, runbook, current source links, and fixture expectations use forge.maximumdirect.net/base-layer/releasekit; a one-time repository API read returned that repository identity.

The complete offline suite passed against the committed implementation:

GOTOOLCHAIN=local GOWORK=off GOPROXY=off GOSUMDB=off \
  go test -mod=readonly -count=1 ./...

The compiled facade/dependency checks and dependency-metadata review passed:

GOTOOLCHAIN=local GOWORK=off GOPROXY=off GOSUMDB=off \
  go run ./internal/apicheck
GOTOOLCHAIN=local GOWORK=off GOPROXY=off GOSUMDB=off \
  go mod tidy -diff

Build/version-injection integration tests passed. An additional disposable consumer removed the original CLI tool declaration, registered the vanity-path CLI through a local source replacement, and ran go tool releasekit version successfully. Its executable imported the root facade and buildinfo and reported the injected v9.8.7 version. These were offline checks using temporary consumer metadata.

The completion review found no original-path references in Go source. Current documentation retains the old path only to explain migration and older releases. A source comparison confirmed that Go changes consist of module-path substitutions and the separately reviewed hosting-fixture updates. Existing release records, ADRs, upstream attribution and policy provenance, dependency checksums, and the Go 1.26.0 minimum are preserved. Documentation links, heading fragments, example shell syntax, formatting, and whitespace checks passed.

The implementation is ready for release preparation. Source publication and fresh consumption of a published vanity-path version remain release follow-up under the procedure above.