diff --git a/docs/release.md b/docs/release.md index ec0c090..829af47 100644 --- a/docs/release.md +++ b/docs/release.md @@ -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: diff --git a/docs/roadmap/migration.md b/docs/roadmap/migration.md deleted file mode 100644 index 2f838d4..0000000 --- a/docs/roadmap/migration.md +++ /dev/null @@ -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. diff --git a/examples/multi-module/woodpecker.yml b/examples/multi-module/woodpecker.yml index 38e11ee..ce5304d 100644 --- a/examples/multi-module/woodpecker.yml +++ b/examples/multi-module/woodpecker.yml @@ -8,7 +8,7 @@ when: steps: - name: deliver - image: golang:1.26.8-bookworm + image: golang:1.26.10-bookworm environment: RELEASEKIT_GITEA_TOKEN: from_secret: releasekit_gitea_token diff --git a/examples/woodpecker/releasekit-source-delivery.yml b/examples/woodpecker/releasekit-source-delivery.yml index acc097b..908c638 100644 --- a/examples/woodpecker/releasekit-source-delivery.yml +++ b/examples/woodpecker/releasekit-source-delivery.yml @@ -4,7 +4,7 @@ when: steps: - name: deliver - image: golang:1.26.8-bookworm + image: golang:1.26.10-bookworm environment: RELEASEKIT_GITEA_TOKEN: from_secret: releasekit_gitea_token diff --git a/examples/woodpecker/tag-delivery.yml b/examples/woodpecker/tag-delivery.yml index fce5958..dc21877 100644 --- a/examples/woodpecker/tag-delivery.yml +++ b/examples/woodpecker/tag-delivery.yml @@ -1,6 +1,6 @@ matrix: include: - - GO_IMAGE: golang:1.26.8-bookworm + - GO_IMAGE: golang:1.26.10-bookworm when: - event: tag