---
title: Go releases
editUrl: https://github.com/Cratis/Chronicle.Go/edit/main/Documentation/releases.md
description: This repository is in early development and has no tagged Go release yet. Repository setup uses no-release; the first implemented, minor-labeled release…
lastUpdated: 2026-10-03T00:00:00.000Z
---

This repository is in early development and has no tagged Go release yet. Repository setup uses `no-release`; the first implemented, minor-labeled release will be v0.1.0. Experimental releases remain v0.x until an approved stable launch.

## Release intent

Every PR has exactly one of `major`, `minor`, `patch`, or `no-release`. While v0.x, use minor for breaking experimental API changes and patch for compatible fixes. Describe breaking changes explicitly in the release notes. Dependabot PRs use `no-release`; a dependency change that needs publication requires a deliberate release-bound maintainer change.

The merged PR body becomes the GitHub Release notes verbatim. Use the [contribution guide](https://github.com/Cratis/Chronicle.Go/blob/main/CONTRIBUTING.md) and PR template, and keep verification and review notes in a PR comment.

## Publication

A push to main runs the Go and Markdown gates before preparing a release. The release action creates the immutable `vX.Y.Z` tag and GitHub Release only after its job succeeds. Dependent jobs read back the release and tag target, fetch the exact version through `proxy.golang.org`, verify the module archive, and request its pkg.go.dev page. Documentation rendering is asynchronous.

There is no separate registry upload or Go publishing credential. GitHub tags are Go module versions; the workflow uses its scoped `GITHUB_TOKEN` for GitHub writes. Keep one runtime root module and the canonical lowercase module path. The [module manifest](https://github.com/Cratis/Chronicle.Go/blob/main/.github/go-modules.json) currently lists only that root; [module policy](/chronicle/go/module-policy/) permits real future nested modules with independent gates. Unpublished tools may preview fetchable pushed root commits without replacements before the first root release; this is source testing, not package publication. Publication-eligible nested modules must instead pin a stable, publicly fetchable root tag. Release source must build without a developer workspace, sibling checkout, secrets, or local replacements.

Wait for Publish to finish before merging another release-bound PR: GitHub concurrency can replace a pending run even when running jobs are not cancelled.

## Major versions

`GO_RELEASE_MAJOR_CEILING` defaults to 0. Set it to 1 only for a maintainer-approved v1 launch and refresh the PR policy check. A major release must be reviewed and merged by a human. Values above 1 are rejected: Go v2+ requires a `/vN` module path, changed imports, and a separately reviewed release design. The current workflow does not publish prereleases or nested modules. Before a real nested publisher is added, require independent version/release-intent handling, protected `<directory>/v*` tags, pre-existing-tag/retry checks and a full fresh-cache proxy/installed-consumer check, following [the shared pattern and its pending live acceptance](/chronicle/go/module-policy/#publication-prerequisites-and-provenance). A `publish` policy flag alone does not publish a module.

## Recovery

If proxy indexing fails after publication, rerun the failed jobs. A full rerun resolves the existing stable release for the same commit and indexes that tag without bumping again. Investigate any conflicting tag or release; never move or delete a published tag. Correct a bad release with a new version and, where appropriate, a Go `retract` directive.

The first public-proxy installation and pkg.go.dev visibility can be verified only after a release exists. Central Cratis documentation publication requires registering this repository in Cratis/Documentation and setting the repository variable `DOCUMENTATION_ENABLED` to `true`; it is independent of Go module indexing.