Simplify source releases with one guarded publication command
This commit is contained in:
@@ -28,7 +28,7 @@ implementing changes. It owns implementation discipline and local commit rules.
|
||||
| LLM clients, prompts, schemas, profiles, or scheduling | [LLM Runtime](internal/llm.md) | It documents the transport boundary and PromptKit integration. |
|
||||
| Output, cache, resume, or debug artifacts | [Run State Internals](internal/state.md), [Operations](operations.md), and [Configuration](config.md) | These separate implementation details, operator behavior, and configuration contracts. |
|
||||
| External input formats, artifact schemas, or durable output files | [Integration Contracts](integrations/) | Integration documents define external and durable data contracts. |
|
||||
| Release preparation, tagging, publication, or verification | [Source Releases](release.md) and [Documentation Policy](policy/documentation.md) | The release procedure owns maintainer guards and immutable-tag recovery; the policy assigns release-note ownership. |
|
||||
| Release preparation, tagging, publication, or optional diagnostics | [Release Policy](policy/release.md) and [Source Releases](release.md) | Policy owns release requirements and completion; the runbook supplies the publication command and recovery procedure. |
|
||||
| Proposed or unimplemented behavior | [Roadmap](roadmap/) | Future work belongs only in roadmap documentation until implemented. |
|
||||
|
||||
For an existing subsystem, also inspect its focused tests and the package-local
|
||||
|
||||
@@ -357,8 +357,9 @@ best-effort development and compilation environment, while Windows is
|
||||
unsupported. Notarius distributes source releases only: an immutable source
|
||||
tag and its checked-in release note identify a release. The project does not
|
||||
publish executable binaries, archives, installers, container images,
|
||||
checksums, signatures, or package-manager entries. Maintainer release commands
|
||||
and tag guards belong to [Source Releases](../release.md).
|
||||
checksums, signatures, or package-manager entries. [Release Policy](release.md)
|
||||
owns publication requirements and completion; maintainer commands and guards
|
||||
belong to [Source Releases](../release.md).
|
||||
|
||||
## Architectural Non-Goals
|
||||
|
||||
|
||||
@@ -91,7 +91,8 @@ secret values.
|
||||
| CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
|
||||
| Configuration contract | `docs/config.md` | Discovery and precedence, file schema, fields, defaults, environment overrides, validation rules, and user-selectable module or validator keys. | Complete example files, CLI syntax, runtime state lifecycle, module implementation details. |
|
||||
| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache, and debug handling, resume, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. |
|
||||
| Source release procedure | `docs/release.md` | Maintainer release selection, candidate validation, tagging, publication guards, verification, and immutable-tag recovery. | Product installation summary, CLI version semantics, historical release summaries, CI implementation detail. |
|
||||
| Release policy | `docs/policy/release.md` | Versioning, compatibility, integrity, immutability, proportionate gate selection, publication controls, and release completion. | Concrete commands, product installation, historical notes, and CI implementation detail. |
|
||||
| Repository-specific release procedure | `docs/release.md` | Prerequisites, candidate preparation, publication command, automated guards, optional diagnostics, and failure recovery. | General release requirements, product installation guidance, historical summaries, and current compatibility contracts. |
|
||||
| Release-note history | `docs/releases/` | One checked-in historical summary for each source release made under the procedure. The note at the immutable tag is that release's record. | Current commands, behavior, contracts, and compatibility definitions. |
|
||||
| Public HTTP contract, if introduced | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. |
|
||||
| Consumer guidance | `docs/consumers/` | Task-oriented subprocess use, minimal client examples, consumer responsibilities, and guidance for any future public package or API. | Wire semantics, external protocol contracts, internal implementation detail. |
|
||||
@@ -125,11 +126,13 @@ other contracts.
|
||||
|
||||
### Releases
|
||||
|
||||
`docs/release.md` owns the source-release procedure. Release notes are
|
||||
The [release policy](release.md) owns requirements and invariants; the
|
||||
[repository procedure](../release.md) owns the commands that satisfy them.
|
||||
Release notes are
|
||||
historical summaries, not current-state contract owners: the checked-in note at
|
||||
an immutable tag records that release, while current canonical documentation
|
||||
must change with the behavior it describes. Do not use a release note to defer
|
||||
or replace current documentation updates.
|
||||
must change with the behavior it describes. Do not use a release procedure or
|
||||
note to weaken policy, redefine current contracts, or defer documentation updates.
|
||||
|
||||
### Contracts And Implementation
|
||||
|
||||
|
||||
204
docs/policy/release.md
Normal file
204
docs/policy/release.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# Release Policy
|
||||
|
||||
**Base Policy Version:** 1.1
|
||||
|
||||
**Last Updated**: 2026-09-25
|
||||
|
||||
**Upstream Source:** `policy` commit `45591a79004c6811950f14dca554f6ff69b7f58e`.
|
||||
|
||||
Notarius adaptations: source-only delivery, lightweight tags, branch-before-tag
|
||||
publication, no prereleases, and the justified native command check below.
|
||||
|
||||
## Purpose
|
||||
|
||||
This policy defines a proportionate workflow for validating and publishing an
|
||||
intended source revision under a fresh version. Releases should require little
|
||||
routine intervention, avoid repeated work, and preserve published contents.
|
||||
|
||||
The repository-specific commands belong in `docs/release.md`. Historical release
|
||||
summaries belong in `docs/releases/`. The procedure must agree with the adopted
|
||||
policy and link to it rather than introduce additional release requirements.
|
||||
|
||||
## Release Model And Completion
|
||||
|
||||
A source release identifies one exact committed source revision through an
|
||||
immutable version tag and a version-matched, checked-in release note. The
|
||||
primary release branch is `main` and the authoritative remote is `origin`.
|
||||
Tags are lightweight. Publish the candidate to `main` before pushing its tag.
|
||||
|
||||
A successful push of the intended tag, with its source commit available on the
|
||||
authoritative primary branch, completes the release. Notarius uses
|
||||
branch-before-tag publication; it does not require an atomic push.
|
||||
|
||||
Release commands must finish at successful publication. They must not wait for
|
||||
or poll CI, require successful CI status, inspect downloadable artifacts, or
|
||||
check consumer installation or Go module availability as completion gates.
|
||||
A failed or ambiguous push requires resolving the authoritative remote state
|
||||
before declaring success or retrying; successful pushes do not require a
|
||||
separate remote read-back gate.
|
||||
|
||||
Notarius publishes source only: no binaries, archives, images, packages,
|
||||
checksums, signatures, or Gitea release objects. Tag CI may provide advisory
|
||||
validation but publishes no deliverables and is not a completion gate.
|
||||
|
||||
## Versioning And Compatibility
|
||||
|
||||
Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
|
||||
no leading zeroes. Notarius does not support prereleases.
|
||||
|
||||
The selected version must be unused locally and on the authoritative remote.
|
||||
Do not require queries to every configured remote or publication service.
|
||||
A version known to have already been published must not be reused, even if the
|
||||
normal guards do not inspect that channel. Adding a distribution channel
|
||||
requires a deliberate update to the policy and procedure where needed.
|
||||
|
||||
For releases at or after `v1.0.0`:
|
||||
|
||||
- a major release may make intentional incompatible changes;
|
||||
- a minor release may add backward-compatible behavior; and
|
||||
- a patch release may make backward-compatible fixes.
|
||||
|
||||
Before `v1.0.0`, a minor release may change a documented public, operational,
|
||||
configuration, data, integration, or compatibility contract when the release
|
||||
note explains the impact and required consumer action. A patch release must
|
||||
not intentionally break those contracts within its minor line.
|
||||
|
||||
Additional compatibility promises and deliberate exceptions belong in the
|
||||
adopted policy or canonical contract documentation. Release notes explain
|
||||
changes; they do not redefine current compatibility contracts.
|
||||
|
||||
## Release Documentation And Preparation
|
||||
|
||||
Every new release must include `docs/releases/<version>.md` in the tagged
|
||||
source tree. Use the complete version tag as the filename and begin with a
|
||||
title containing the product name and that exact version.
|
||||
|
||||
Include a short summary and any relevant compatibility impact or upgrade
|
||||
instructions. Keep the note proportionate to the change. Fixed sections and
|
||||
explicit no-action boilerplate are not required. Existing historical notes
|
||||
need not be rewritten to adopt this format.
|
||||
|
||||
Keep exact current contracts in their canonical documents and update affected
|
||||
documentation with the behavior change. Link to those documents from the note
|
||||
where useful. A release note must not substitute for current documentation.
|
||||
Do not create retrospective notes for the pre-procedure v0.1.0, v0.2.0, or
|
||||
v0.3.0 tags.
|
||||
|
||||
Version selection, release-note content, and retirement of completed roadmaps
|
||||
are preparation responsibilities, not separate human approval gates. Preserve
|
||||
planned and deferred work and repair affected links when retiring roadmaps.
|
||||
Ordinary change review covers unintended files, credentials, and private data;
|
||||
do not repeat it as a release-specific sign-off. Ignored local files are not
|
||||
prohibited merely because they exist: they are not included in the tagged source.
|
||||
|
||||
## Candidate Validation
|
||||
|
||||
Provide one publication command that validates the final committed candidate,
|
||||
checks publication state, and publishes the intended refs. A validation-only
|
||||
mode or command may be provided for diagnosis, but must not be a required step
|
||||
before publication repeats the same checks.
|
||||
|
||||
Run the complete deterministic, offline default test suite once for the final
|
||||
candidate, following the [testing policy](testing.md). For repositories that
|
||||
publish builds, verify the required build targets. Select those targets for
|
||||
the application's actual support commitments; native testing on each platform
|
||||
and access to particular hardware are not default release prerequisites.
|
||||
|
||||
Additional gates must address a concrete risk that the existing checks do not
|
||||
adequately cover. Do not automatically require linting, race testing, module
|
||||
hygiene audits, documentation audits, credential scans, example validation, or
|
||||
expanded platform matrices solely because they are possible. Retain such
|
||||
checks when their distinct protection justifies their cost. A one-time migration
|
||||
check must not silently become a permanent release requirement.
|
||||
|
||||
Release tests must not require real credentials, mutable application services,
|
||||
paid APIs, provider probes, or inference calls. The procedure may describe dependency
|
||||
preparation separately from offline validation.
|
||||
|
||||
Avoid duplicate validation across release phases. Successful checks for the
|
||||
same final candidate need not be repeated solely to satisfy another phase;
|
||||
any reuse must clearly apply to that exact candidate. Persistent validation
|
||||
caches are not required. If the candidate changes, validate the new candidate.
|
||||
Cheap publication-state checks may be repeated immediately before pushing
|
||||
because local or remote state may have changed during validation.
|
||||
|
||||
Automate mechanical guards. Human review gates are strongly disfavored: add one
|
||||
only through an explicit project-specific policy decision explaining the
|
||||
concrete risk and why ordinary change review or automation is insufficient.
|
||||
Do not add routine confirmations for checks the command can perform itself.
|
||||
|
||||
### Notarius Gate Selection
|
||||
|
||||
Run the default offline Go suite once and build the native `cmd/notarius` with
|
||||
release version injection, checking its `--version` output. The command check
|
||||
protects the actual executable entry point and linker-supplied version, which
|
||||
package tests alone do not verify. Build products are temporary, not published.
|
||||
Use `GOWORK=off` so a sibling checkout cannot substitute for declared dependencies.
|
||||
|
||||
Race tests, standalone vet, formatting/whitespace checks, module tidy audits,
|
||||
standalone example validation, and Linux/Darwin cross-builds remain useful
|
||||
change-specific development checks, not mandatory release gates. Default tests
|
||||
already cover maintained examples. Source-only publication does not require a
|
||||
binary distribution matrix. No new platform or hardware prerequisites are added.
|
||||
|
||||
## Publication Guards
|
||||
|
||||
Automate the checks needed to publish the intended source under a fresh version:
|
||||
|
||||
- the version has the adopted format and is unused locally and on the
|
||||
authoritative remote;
|
||||
- the worktree and index are clean on the primary release branch;
|
||||
- the source being published is the exact candidate that passed validation,
|
||||
including its matching release note;
|
||||
- the branch push advances authoritative `main` to the candidate without
|
||||
discarding remote history, before the tag is published; and
|
||||
- the tag identifies the validated candidate and only the intended refs are
|
||||
published.
|
||||
|
||||
Fetch the authoritative branch and tag state as needed for these checks.
|
||||
Do not force branch or tag updates to bypass a failed guard. Publish explicit
|
||||
refs rather than all local tags. Do not require CI success, publication-service
|
||||
availability checks, or a separate manual confirmation for each guard.
|
||||
|
||||
## Immutability And Failure Recovery
|
||||
|
||||
Published version tags and published contents are immutable. Do not move,
|
||||
overwrite, recreate, or delete a published tag, or replace a published artifact,
|
||||
checksum, signature, provenance statement, or release note under that version.
|
||||
The checked-in note at the immutable tag is that release's historical record.
|
||||
|
||||
If validation fails before publication, correct and commit the candidate and
|
||||
rerun the publication command. If a push fails or its outcome is ambiguous,
|
||||
inspect the authoritative remote before retrying. Remove an unpublished local
|
||||
tag only after confirming it was never published or used by a release channel.
|
||||
An unavailable remote leaves publication status unknown; do not overwrite a tag
|
||||
to resolve uncertainty.
|
||||
|
||||
Transient network, authentication, CI, or consumer-availability failures do not
|
||||
by themselves require a new version. Advisory CI or optional installation checks
|
||||
may be retried against the same immutable tag. Notarius has no asynchronous
|
||||
artifact delivery to recover.
|
||||
|
||||
A defect requiring changes to published source or contents requires a corrected
|
||||
commit, a new semantically appropriate version, a matching release note, and
|
||||
the release procedure again. Leave the original release intact. A channel's
|
||||
yank, deprecation, or advisory mechanism may warn consumers away from a defective
|
||||
release without replacing its contents or reusing its version.
|
||||
|
||||
## Repository Release Procedure
|
||||
|
||||
Maintain `docs/release.md` as a short, executable maintainer runbook. It must
|
||||
identify:
|
||||
|
||||
1. prerequisites, primary branch, and authoritative remote;
|
||||
2. version and release-note preparation;
|
||||
3. one publication command with its selected local checks and automated guards;
|
||||
4. declared deliverables, required build targets, and automation responsibilities;
|
||||
5. the successful-push completion point and separately reported delivery status;
|
||||
and
|
||||
6. failure handling and ambiguous-push recovery.
|
||||
|
||||
Use copyable commands where practical. Keep optional diagnostics and consumer
|
||||
verification clearly optional. The procedure must not turn preparation work,
|
||||
ordinary change review, or post-publication investigation into additional
|
||||
release gates.
|
||||
208
docs/release.md
208
docs/release.md
@@ -1,164 +1,84 @@
|
||||
# Source Releases
|
||||
|
||||
This procedure is for maintainers publishing Notarius source releases. A
|
||||
release is an immutable lightweight `vMAJOR.MINOR.PATCH` tag on `main` together
|
||||
with its checked-in `docs/releases/<tag>.md` note. Tag CI validates that source
|
||||
candidate after publication; it does not publish or repair a release.
|
||||
This is the executable runbook for [Release Policy](policy/release.md).
|
||||
Notarius publishes an immutable lightweight tag and its checked-in release note,
|
||||
not binaries or Gitea release objects. Linux is supported; macOS is best-effort
|
||||
for development, and Windows is unsupported. `main` on `origin` is authoritative.
|
||||
|
||||
Notarius publishes no binaries, archives, checksums, signatures, containers,
|
||||
package-manager entries, or Gitea release objects. Windows is not supported.
|
||||
Do not create retrospective notes for the pre-procedure `v0.1.0`, `v0.2.0`, or
|
||||
`v0.3.0` tags.
|
||||
## Prepare
|
||||
|
||||
## Select And Describe The Release
|
||||
|
||||
Choose an unused stable semantic version in the form `vMAJOR.MINOR.PATCH`.
|
||||
Prereleases are not supported. Before `v1.0.0`, a minor release may change a
|
||||
documented CLI, configuration, durable artifact, integration, or operating
|
||||
contract when its note explains the impact and required operator action. A
|
||||
patch release must not intentionally break those documented contracts within
|
||||
its minor line.
|
||||
|
||||
Create the version-matched note as part of the candidate. Every new note uses
|
||||
this structure, with concise, truthful content in each section:
|
||||
|
||||
```markdown
|
||||
# Notarius vMAJOR.MINOR.PATCH
|
||||
|
||||
This release ...
|
||||
|
||||
## Summary
|
||||
|
||||
## Compatibility
|
||||
|
||||
## Upgrade
|
||||
|
||||
## Changes
|
||||
```
|
||||
|
||||
The note is a historical summary. Link to current canonical documentation for
|
||||
exact behavior, and update that documentation in the candidate rather than
|
||||
using the note as a substitute.
|
||||
|
||||
## Prepare The Candidate
|
||||
|
||||
Set the selected release version and disable Go workspace use for every
|
||||
candidate command:
|
||||
Use Git, a POSIX shell, and Go 1.25.5 or newer. Configure ordinary Git credentials
|
||||
for `origin` and private-module access without putting secrets in the repository.
|
||||
Prepare dependencies before offline validation where necessary:
|
||||
|
||||
```sh
|
||||
RELEASE_VERSION=vMAJOR.MINOR.PATCH
|
||||
export RELEASE_VERSION GOWORK=off
|
||||
GOWORK=off GOPRIVATE=gitea.maximumdirect.net go mod download
|
||||
```
|
||||
|
||||
Run the shared source-candidate checks from the repository. They cover module
|
||||
hygiene, tests, race tests, vet, builds, formatting, whitespace, maintained
|
||||
configuration validation, and the Linux and Darwin command-build matrix:
|
||||
Choose an unused stable version under the policy's compatibility rules. Add
|
||||
`docs/releases/<version>.md`, starting with `# Notarius <version>`, with a concise
|
||||
summary and relevant compatibility/upgrade information. No fixed section list is
|
||||
required. Update current documentation with behavior changes; retire only
|
||||
completed roadmaps and preserve planned/deferred work. Commit the candidate on
|
||||
`main` after ordinary change review. There is no separate release sign-off.
|
||||
|
||||
## Publish
|
||||
|
||||
Run one command from the repository with the actual selected version:
|
||||
|
||||
```sh
|
||||
./scripts/check-release-source.sh "$RELEASE_VERSION"
|
||||
./scripts/release.sh vMAJOR.MINOR.PATCH
|
||||
```
|
||||
|
||||
Before committing, manually follow every changed local Markdown link and
|
||||
review the candidate for unintended files, generated output, credentials, or
|
||||
other unrelated changes. Commit the release note and all affected current
|
||||
documentation, then run the shared checker against that exact candidate. Push
|
||||
the candidate commit to `main` only after it succeeds. Record the exact commit
|
||||
only after that push:
|
||||
The command checks version availability on `origin`, branch and worktree state,
|
||||
and the matching note. It runs the complete offline default test suite once and
|
||||
a native CLI build/version check with `GOWORK=off`. The
|
||||
[gate rationale](policy/release.md#notarius-gate-selection) explains the selected
|
||||
checks. It then rechecks candidate and publication state, pushes the exact
|
||||
candidate to `main` without force, creates a lightweight tag, and pushes only
|
||||
that tag. It neither rewrites history nor publishes other local tags.
|
||||
|
||||
A successful tag push completes the source release. The command does not wait
|
||||
for CI or verify consumer installation/module availability. Tag CI is advisory
|
||||
validation only; there are no asynchronous deliverables to await.
|
||||
|
||||
## Failure And Recovery
|
||||
|
||||
Before publication, correct failed checks, commit any changes, and rerun the
|
||||
command. If the candidate changes during validation, validation must run again
|
||||
on the new candidate. A failed branch push publishes no tag.
|
||||
|
||||
On a failed or ambiguous push, the command queries the affected remote ref. If
|
||||
a tag push reports failure but the intended lightweight tag is confirmed on the
|
||||
remote, publication succeeded. Otherwise it stops and reports failure or unknown
|
||||
status, leaving any local tag intact for inspection. Do not blindly rerun, force
|
||||
push, or delete a possibly published tag.
|
||||
|
||||
Inspect authoritative state before retrying:
|
||||
|
||||
```sh
|
||||
RELEASE_COMMIT=$(git rev-parse 'HEAD^{commit}')
|
||||
export RELEASE_COMMIT
|
||||
git ls-remote origin refs/heads/main refs/tags/vMAJOR.MINOR.PATCH
|
||||
git rev-parse vMAJOR.MINOR.PATCH
|
||||
```
|
||||
|
||||
For private-module installation, configure standard `GOPRIVATE` matching this
|
||||
module and ordinary Git authentication for the hosting service before running
|
||||
the verification below. The exact authentication mechanism belongs to the
|
||||
maintainer environment; never record credentials or environment dumps in a
|
||||
release note, command history, or repository file.
|
||||
If the intended tag exists remotely, leave it immutable. If it is absent and
|
||||
you have confirmed that the local tag was never published or used by a release
|
||||
channel, remove only that unpublished local tag, then rerun the command. A
|
||||
failed remote query is not proof of absence. Network/authentication failures
|
||||
alone do not require a new version. A defect requiring changes to published
|
||||
source requires a new semantically appropriate version and matching note.
|
||||
|
||||
## Guard And Publish The Tag
|
||||
## Optional Diagnostics
|
||||
|
||||
Fetch current remote references, then run this guard without editing the
|
||||
candidate. It requires `main`, a clean worktree and index, disabled workspace
|
||||
use, a stable release version, the recorded and pushed commit, a matching note,
|
||||
and unused local and remote tags:
|
||||
`./scripts/check-release-source.sh <version>` runs validation without publication.
|
||||
It is useful for diagnosis, but is not a required preliminary step that must
|
||||
repeat the publication command's checks.
|
||||
|
||||
```sh
|
||||
git fetch origin main --tags
|
||||
Race tests, vet, module hygiene, formatting, example checks, and cross-builds may
|
||||
be run when relevant to a change; they are not additional release gates. The
|
||||
development guide and testing policy govern change-specific verification.
|
||||
|
||||
if ! printf '%s\n' "$RELEASE_VERSION" |
|
||||
grep -E -x 'v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)' >/dev/null
|
||||
then
|
||||
printf '%s\n' "invalid release version: $RELEASE_VERSION" >&2
|
||||
exit 1
|
||||
fi
|
||||
test "$GOWORK" = off
|
||||
test "$(git branch --show-current)" = main
|
||||
test -z "$(git status --porcelain)"
|
||||
test "$RELEASE_COMMIT" = "$(git rev-parse 'HEAD^{commit}')"
|
||||
test "$RELEASE_COMMIT" = "$(git rev-parse 'origin/main^{commit}')"
|
||||
test -s "docs/releases/$RELEASE_VERSION.md"
|
||||
grep -F -x "# Notarius $RELEASE_VERSION" "docs/releases/$RELEASE_VERSION.md"
|
||||
for heading in '## Summary' '## Compatibility' '## Upgrade' '## Changes'; do
|
||||
grep -F -x "$heading" "docs/releases/$RELEASE_VERSION.md"
|
||||
done
|
||||
if git rev-parse -q --verify "refs/tags/$RELEASE_VERSION" >/dev/null; then
|
||||
printf '%s\n' "local tag already exists: $RELEASE_VERSION" >&2
|
||||
exit 1
|
||||
fi
|
||||
if git ls-remote --exit-code --tags origin "refs/tags/$RELEASE_VERSION" >/dev/null 2>&1; then
|
||||
printf '%s\n' "remote tag already exists: $RELEASE_VERSION" >&2
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
Create an explicitly lightweight tag against the guarded commit, verify its
|
||||
target, and push only that tag ref:
|
||||
|
||||
```sh
|
||||
git -c tag.gpgSign=false tag "$RELEASE_VERSION" "$RELEASE_COMMIT"
|
||||
test "$(git cat-file -t "$RELEASE_VERSION")" = commit
|
||||
test "$(git rev-parse "$RELEASE_VERSION^{commit}")" = "$RELEASE_COMMIT"
|
||||
git push origin "refs/tags/$RELEASE_VERSION:refs/tags/$RELEASE_VERSION"
|
||||
```
|
||||
|
||||
Never use `git push --tags`, move a published tag, or delete a published tag.
|
||||
|
||||
## Verify The Published Release
|
||||
|
||||
Confirm that the remote tag still points at the guarded commit and that the
|
||||
note is available from the tagged tree:
|
||||
|
||||
```sh
|
||||
REMOTE_TAG_COMMIT=$(git ls-remote origin "refs/tags/$RELEASE_VERSION" | awk '{print $1}')
|
||||
test "$REMOTE_TAG_COMMIT" = "$RELEASE_COMMIT"
|
||||
git show "$RELEASE_VERSION:docs/releases/$RELEASE_VERSION.md" >/dev/null
|
||||
```
|
||||
|
||||
Verify a fresh source installation and its diagnostic version. The temporary
|
||||
directory confines the installed command to this check:
|
||||
|
||||
```sh
|
||||
release_verification_dir=$(mktemp -d)
|
||||
trap 'rm -rf "$release_verification_dir"' 0 HUP INT TERM
|
||||
mkdir -p "$release_verification_dir/bin"
|
||||
GOWORK=off GOBIN="$release_verification_dir/bin" go install \
|
||||
"gitea.maximumdirect.net/eric/notarius/cmd/notarius@$RELEASE_VERSION"
|
||||
test "$("$release_verification_dir/bin/notarius" --version)" = "notarius $RELEASE_VERSION"
|
||||
```
|
||||
|
||||
An exact fresh checkout and `GOWORK=off go build ./cmd/notarius` is an
|
||||
equivalent source verification when local installation policy requires it.
|
||||
`notarius --version` is diagnostic only; downstream compatibility remains
|
||||
defined by the published receipt and artifact contracts.
|
||||
|
||||
## Failure And Correction Policy
|
||||
|
||||
If candidate validation fails before publication, fix the candidate on `main`,
|
||||
rerun the shared checker, and repeat the guards. An unpublished local tag may
|
||||
be deleted after inspection.
|
||||
|
||||
If the remote tag or tag CI reveals a defect, leave the published tag intact.
|
||||
Fix the defect on `main`, choose a new patch version, write a new matching
|
||||
note, and repeat this procedure. Do not weaken tag immutability or add release
|
||||
assets as a workaround.
|
||||
A fresh source install or exact-tag checkout/build may be used to investigate
|
||||
consumer availability after release. Such checks are optional and do not delay
|
||||
or reverse release completion. `notarius --version` is diagnostic; subprocess
|
||||
compatibility is defined by the receipt and artifact contracts.
|
||||
|
||||
Reference in New Issue
Block a user