Plan the ReleaseKit vanity module migration

2026-11-01 14:24:43 +00:00
parent 7d033c5ca1
commit f97edeb830
1 changed files with 174 additions and 0 deletions
--- a/docs/roadmap/migration.md
+++ b/docs/roadmap/migration.md
@@ -0,0 +1,174 @@
+# Roadmap: migrate to the ReleaseKit vanity module path
+
+Status: proposed; implementation has not started.
+
+## 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](../policy/release.md#versioning-and-compatibility) governs
+version selection and compatibility.
+
+## Current baseline
+
+The baseline is v0.4.2, commit
+`7d033c5ca1c95aec7db9690293638a0a1ac887b8`.
+
+- [go.mod](../../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](../../releasekit.json) and
+  [maintainer runbook](../release.md) still identify the older Gitea host and
+  repository location.
+
+### 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](https://go.dev/ref/mod#module-path).
+
+## 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](../policy/architecture.md).
+- 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.
+- 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](../../internal/versioncontract/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](../../internal/apicheck/main.go), 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](../../examples/woodpecker/tag-delivery.yml),
+  [multi-module workflow](../../examples/multi-module/woodpecker.yml), and
+  [multi-module launcher](../../examples/multi-module/release.sh).
+- 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.
+- Review live repository URLs and delivery settings separately from module
+  identifiers. The vanity path names Go packages; the forge owns Git transport,
+  source navigation, and hosted release pages. Resolve the delivery question
+  below and update its owning configuration and runbook accordingly.
+
+### 4. Verify the migration
+
+Use the existing [testing policy](../policy/testing.md) and
+[development guide](../development.md#validation) 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](../release.md). 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.
+
+## Open Decisions
+
+### Destination for ReleaseKit's hosted release pages
+
+**Recommendation:** Align ReleaseKit's own delivery profile and maintainer
+guidance with the Forgejo repository at `forge.maximumdirect.net`, owner
+`base-layer`, repository `releasekit`. Confirm the destination's supported
+Gitea-compatible API and credential setup when configuring delivery. This
+matches the existing Git remote and vanity mapping and gives maintainers one
+repository location for source and hosted release pages. It requires updating
+delivery configuration, related fixture expectations, and current hosting links
+where appropriate.
+
+**Alternative:** Retain the existing Gitea delivery endpoint if it remains an
+intentional alias or supported delivery destination. This can preserve working
+automation and reduce hosting changes during the module migration. Its value
+depends on that endpoint continuing to address the intended repository; the
+runbook would need to explain the relationship to the Forgejo origin.
+
+This hosting choice is independent of the module declaration. Source migration
+and offline verification can proceed while the delivery destination is resolved.