diff --git a/docs/roadmap/migration.md b/docs/roadmap/migration.md new file mode 100644 index 0000000..2a79749 --- /dev/null +++ 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.