|
|
|
|
@@ -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.
|
