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