Skip to content

Prepare the v0.4.0 changelog and documents for publication - #18

Merged
sshaplygin merged 1 commit into
mainfrom
v04/release-prep
Nov 4, 2026
Merged

sshaplygin merged 1 commit into
mainfrom
v04/release-prep

Conversation

@sshaplygin

@sshaplygin sshaplygin commented Nov 4, 2026 •

Copy link
Copy Markdown
Owner

Prepares the documents for publishing v0.4.0. No tag is created by this PR. After it merges, the eight v0.4.0 tags go on the merge commit (see "After merge" below).

Why

Four statements were true for a candidate and become false once v0.4.0 is tagged:

File:line (base 6df4600) Before After (line on this branch)
CHANGELOG.md:7 ## [Unreleased] — v0.4.0 candidate ## [Unreleased] (empty) then ## [0.4.0] — 2026-11-04 (lines 7-9)
docs/releasing.md:3-4 "The next release candidate is v0.4.0 ... does not mean that version has been published." Names v0.4.0 as the release version, says a passing candidate check publishes nothing, and says a version counts as published only once its tags are pushed and make release-check-published confirms it (lines 3-6)
site/index.html:33 JSON-LD "version": "0.3.1" "version": "0.4.0"
site/index.html:232 pre-1.0, <b>v0.4 candidate</b> pre-1.0, <b>v0.4.0</b>

One related wording change: docs/releasing.md:56-57 (now 58-59) introduces the publishing table as "the v0.4.0 release set is these eight tags, pushed in dependency order" instead of "Publish these tags in dependency order". The table itself is unchanged.

Statements left as they were, because they stay true after publication: the FIFO module is "unreleased", "unpublished" or "has not been tagged" (site/index.html:296-297, docs/policies.md:87-88,156-157); "excluded from v0.4" (README.md:30, docs/evidence.md:142-143); and the generic candidate-check procedure in docs/releasing.md, which still applies to later versions. release-version stays v0.4.0.

Changelog audit (v0.3.1..main, 64 non-merge commits)

apidiff -m was run on each of the eight release modules (v0.3.1 export data against 6df4600 export data):

  • bandit: 35 incompatible removals. All are already listed under Breaking API change: the distributed bandit, Store/MemStore, the coordination types, constants, defaults and the seven sentinel errors.
  • root: compatible additions only. These are Settings.MigrationMaxRequests, ErrInvalidMigrationMaxRequests, S3FIFO and SIEVE.
  • lfu, policies, policies/arc, policies/tinylfu, metrics, benchclient: no exported API change. benchclient.DefaultArms still builds LRU, LFU, 2Q and Random; only its doc comment changed.

The audit added these entries to the [0.4.0] section:

  • Removed: bandit/redis is not tagged at v0.4.0; its last version is bandit/redis/v0.3.1.
  • Removed: the per-release notes pages (docs/release-notes-v0.1.0.md .. v0.3.1.md) and docs/fleet.md. All five existed at v0.3.1.
  • Changed: the Bandit contract no longer requires non-blocking methods. Under EpochRequests, the Get that completes an epoch still waits for the bandit.
  • Added: ErrInvalidMigrationMaxRequests, which rejects a negative MigrationMaxRequests.
  • Added: the PolicyType constants S3FIFO and SIEVE, appended after TinyLFU, so existing values keep their numbers.
  • Link definitions: [Unreleased] (compare v0.4.0...HEAD), [0.4.0], and the missing [0.3.1], in the file's existing releases/tag/ style. The [0.4.0] and compare links resolve only after the tag is pushed.

The audit found nothing else missing. The FIFO exclusion, the stitchfix removal, the epoch, stability and migration fixes, and the evidence changes were already covered.

The date 2026-11-04 is today's date. If this merges on a later day, adjust it before merging.

Preflight on origin/main (6df4600)

Check Result
make all in a detached worktree exit 0, 143 s. Release checker: "Validating committed source 6df4600"; "Candidate consumer checks passed for 8 modules"; golangci-lint "0 issues" on all 12 modules; make fmt left the worktree clean
Local v0.4* tags none
git ls-remote --tags origin 28 tags, none matching v0.4
go list -m <module>@v0.4.0 with GOPROXY=https://proxy.golang.org GOFLAGS=-mod=mod GOWORK=off, empty temp module, fresh GOMODCACHE all 8 modules exit 1, 404 Not Found ... invalid version: unknown revision <tag>
GitHub CI on 6df4600 CI, Pages and Dependency Graph runs all success

Verification on this branch (1f434a4)

  • make all in a detached worktree: exit 0, 136 s. "Validating committed source 1f434a4", "Candidate consumer checks passed for 8 modules". The worktree was clean afterwards.
  • python3 scripts/record_evidence.py --verify bench/results/current: exit 0, "Verified 16 artifacts and generated report at 1cb65fe".
  • Diff: 3 files (CHANGELOG.md, docs/releasing.md, site/index.html), +27/-8. No Go source, go.mod, evidence data or release-version change.

Note on timing

Merging touches site/, so the Pages workflow deploys a site that shows v0.4.0 before the tags exist. Tag the merge commit soon after merging to keep that window short.

After merge (not part of this PR)

  1. Re-run make release-check at the merge commit.
  2. Create the eight tags from docs/releasing.md on that commit, in the listed order, and push them.
  3. Run make release-check-published.
  4. Create the GitHub release v0.4.0 from the [0.4.0] section and mark it latest.
  5. Repin go-cache-bench to the v0.4.0 tags.

Tags v0.3.0 and v0.3.1 have no GitHub release object; the latest GitHub release is v0.2.0. This PR does not address that.

The changelog opened with "[Unreleased] — v0.4.0 candidate", docs/releasing.md
called v0.4.0 "the next release candidate", and the site showed "v0.4
candidate" with a JSON-LD version of 0.3.1. Each of these becomes false once
the eight v0.4.0 tags are pushed from this commit's merge.

CHANGELOG.md: the section becomes "[0.4.0] — 2026-11-04" under an empty
"[Unreleased]", with link definitions for [Unreleased], [0.4.0] and the
missing [0.3.1]. An audit against v0.3.1..main (apidiff per module, and the
commit log) added what the section omitted: the ErrInvalidMigrationMaxRequests
sentinel, the S3FIFO and SIEVE PolicyType constants in the root module, the
relaxed Bandit blocking contract and the Get that still waits for it under
EpochRequests, the removed release-notes and fleet pages, and that
bandit/redis ends at v0.3.1. apidiff reports no incompatible change outside
the bandit module, and every bandit removal is already listed.

docs/releasing.md: the opening states the release version and that it is
published only once its tags are pushed and confirmed by
make release-check-published; the publishing table is introduced as the
v0.4.0 release set.

No Go source, evidence data or release-version change.
@sshaplygin
sshaplygin merged commit 5ed2dbb into main Nov 4, 2026
25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant