Prepare v0.5.0 with the current Go toolchain and retire the migration roadmap
This commit is contained in:
@@ -14,7 +14,7 @@ succeeded. CI and consumer installation are not completion checks.
|
||||
|
||||
## Prepare a candidate
|
||||
|
||||
Use a clean clone on `main`. The chosen build toolchain is Go 1.26.8. Make that
|
||||
Use a clean clone on `main`. The chosen build toolchain is Go 1.26.10. Make that
|
||||
local installation the active `go` command for preparation, building the release
|
||||
executable, and candidate validation:
|
||||
|
||||
|
||||
@@ -1,207 +0,0 @@
|
||||
# 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](../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.
|
||||
|
||||
## 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:
|
||||
|
||||
```sh
|
||||
GOTOOLCHAIN=local GOWORK=off GOPROXY=off GOSUMDB=off \
|
||||
go test -mod=readonly -count=1 ./...
|
||||
```
|
||||
|
||||
The compiled facade/dependency checks and dependency-metadata review passed:
|
||||
|
||||
```sh
|
||||
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.
|
||||
Reference in New Issue
Block a user