161 lines
8.4 KiB
Markdown
161 lines
8.4 KiB
Markdown
# Roadmap: migrate to the ReleaseKit vanity module path
|
|
|
|
Status: implementation in place; final verification and completion review underway.
|
|
|
|
## 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.
|
|
|
|
## Baseline at start of migration
|
|
|
|
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.
|
|
|
|
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](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.
|
|
- 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](../../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.
|
|
- 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](../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.
|