Skip to content

fix(docs): anchor release dates to git tags and replace the release guards #183

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
flyingrobots wants to merge 4 commits into
base: main
Choose a base branch
from
Open

fix(docs): anchor release dates to git tags and replace the release guards #183

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
431ed87
fix(docs): realign release dates to actual git tag dates
flyingrobots Aug 4, 2026
89ca929
refactor(xtask): reconcile release dates against tags, not against co…
flyingrobots Aug 4, 2026
035d60b
fix(review): address CodeRabbit findings on release date reconciliation
flyingrobots Aug 4, 2026
528dc31
style(changelog): merge the duplicate Unreleased "Changed" sections
flyingrobots Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,23 @@ jobs:
- name: Provider component fixture inventory
run: cargo +"${{ matrix.rust-version }}" xtask provider-component-fixtures --check

release-dates:
name: release-dates (git tag reconciliation)
runs-on: ubuntu-latest
steps:
# The reconciliation compares recorded dates against the tags that
# published them, so this job needs the tags. The default shallow
# checkout fetches none, which is why this cannot ride along on the
# matrix job above.
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
with:
persist-credentials: false
fetch-depth: 0
- name: Install Rust
run: rustup toolchain install stable --profile minimal
- name: Reconcile release dates against git tags
run: cargo +stable xtask release-dates --check

supply-chain:
name: supply-chain (cargo-deny)
runs-on: ubuntu-latest
Expand Down
262 changes: 137 additions & 125 deletions CHANGELOG.md
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/releases/v0.1.0-alpha.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# v0.1.0-alpha.1 Release Notes

Target date: 2026-06-24
Target date: 2026-06-21

Status: published as a GitHub prerelease from the signed `v0.1.0-alpha.1` tag
on 2026-06-21.
Expand Down
2 changes: 1 addition & 1 deletion docs/releases/v0.10.0-alpha.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# v0.10.0-alpha.1 Release Notes

Target date: 2026-10-21
Target date: 2026-06-29

Status: published GitHub prerelease notes for `v0.10.0-alpha.1`, with
post-publication evidence recorded on `main`.
Expand Down
2 changes: 1 addition & 1 deletion docs/releases/v0.11.0-alpha.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# v0.11.0-alpha.1 Release Notes

Target date: 2026-11-04
Target date: 2026-06-30

Status: published GitHub prerelease notes for `v0.11.0-alpha.1`, with
post-publication evidence recorded on `main`.
Expand Down
2 changes: 1 addition & 1 deletion docs/releases/v0.2.0-alpha.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# v0.2.0-alpha.1 Release Notes

Target date: 2026-07-01
Target date: 2026-06-21

Status: published as a GitHub prerelease from the signed `v0.2.0-alpha.1` tag
on 2026-06-21.
Expand Down
2 changes: 1 addition & 1 deletion docs/releases/v0.3.0-alpha.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# v0.3.0-alpha.1 Release Notes

Target date: 2026-07-15
Target date: 2026-06-24

Status: published as a GitHub prerelease from the signed `v0.3.0-alpha.1` tag
targeting `4ea3d993f74490b495fe6e6a9ec2d52f889ccceb`.
Expand Down
2 changes: 1 addition & 1 deletion docs/releases/v0.4.0-alpha.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# v0.4.0-alpha.1 Release Notes

Target date: 2026-07-29
Target date: 2026-06-25

Status: published as a GitHub prerelease from the signed `v0.4.0-alpha.1` tag
targeting `65c80ce4660b384ebf9fd482c59fff402f34d47b`.
Expand Down
2 changes: 1 addition & 1 deletion docs/releases/v0.5.0-alpha.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# v0.5.0-alpha.1 Release Notes

Target date: 2026-08-12
Target date: 2026-06-25

Status: published as a GitHub prerelease from the `v0.5.0-alpha.1` tag
targeting `e680adf0a3ccc72559d1c4710e81010738918532`.
Expand Down
2 changes: 1 addition & 1 deletion docs/releases/v0.6.0-alpha.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# v0.6.0-alpha.1 Release Notes

Target date: 2026-08-26
Target date: 2026-06-26

Status: published as a GitHub prerelease from the `v0.6.0-alpha.1` tag
targeting `ec1ce8a5186801caa3c627c6714cedff7fdf43bc`.
Expand Down
2 changes: 1 addition & 1 deletion docs/releases/v0.7.0-alpha.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# v0.7.0-alpha.1 Release Notes

Target date: 2026-09-09
Target date: 2026-06-27

Status: published GitHub prerelease notes for `v0.7.0-alpha.1`, with
post-publication evidence recorded on `main`.
Expand Down
2 changes: 1 addition & 1 deletion docs/releases/v0.8.0-alpha.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# v0.8.0-alpha.1 Release Notes

Target date: 2026-09-23
Target date: 2026-06-28

Status: published GitHub prerelease notes for `v0.8.0-alpha.1`, with
post-publication evidence recorded on `main`.
Expand Down
2 changes: 1 addition & 1 deletion docs/releases/v0.9.0-alpha.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# v0.9.0-alpha.1 Release Notes

Target date: 2026-10-07
Target date: 2026-06-28

Status: published GitHub prerelease notes for `v0.9.0-alpha.1`, with
post-publication evidence recorded on `main`.
Expand Down
35 changes: 31 additions & 4 deletions docs/topics/release-process/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,37 @@ captured in [`policy.toml`](./policy.toml). [RELEASE-REQ-009]
`cargo xtask release-prep <version>` scaffolds the mechanical release-prep
surfaces that must move together: workspace package versions, lockfile package
versions, a dated changelog section, release policy boundary block, release
notes stub, release boundary test stub, changelog date guard entry, and paired
release-process test-plan rows. The command does not write the release thesis,
replace topic-shelf audits, or decide scope/non-goals; reviewers must replace
the scaffold placeholders before release. [RELEASE-REQ-024]
notes stub, and paired release-process test-plan rows. The command does not
write the release thesis, replace topic-shelf audits, decide scope/non-goals, or
generate Rust test stubs; reviewers must replace the scaffold placeholders
before release. [RELEASE-REQ-024]

`cargo xtask release-dates` reconciles the dates recorded in the release policy,
`CHANGELOG.md`, and `docs/releases/*.md` against the git tags that published
them. Those three surfaces are written from one field at scaffold time, so
comparing them against each other only proves the copy succeeded; the tags are
the independent authority for when a release happened. The check runs inside
`cargo xtask verify` and reports uncovered surfaces separately from date drift.
A clone without tags fails rather than passing silently, because a missing
independent authority is not approval. [RELEASE-REQ-008]

For a published release, `target_date` in [`policy.toml`](./policy.toml) and
`Target date:` in `docs/releases/*.md` record the date the release was tagged,
not a date it was planned for and not the GitHub Release publication timestamp.
`v0.4.0-alpha.1` shows the difference: tagged 2026-06-24, published 2026-06-25.
The field keeps its scaffold-era name because the reconciliation parses that
exact literal. [RELEASE-REQ-008]

Tag dates are read in UTC. `%(taggerdate)` renders in the reading machine's
timezone by default, so a tag created near midnight resolves to different days
for different operators. `v0.4.0-alpha.1` is such a tag: 2026-06-24 in PDT and
2026-06-25 in UTC. The recorded date is the UTC one, so a local run and a CI run
agree. [RELEASE-REQ-008]

Release tags must be annotated. A lightweight tag has no tagger date, so the
check would fall back to the tagged commit's committer date and a tag placed on
an older commit would report a date that never corresponded to a release. The
reconciliation rejects lightweight `v*` tags instead. [RELEASE-REQ-008]

Every release-prep branch must audit `docs/topics/` coverage and accuracy before
the release-prep pull request opens. Coverage is audited topic shelves divided
Expand Down
22 changes: 10 additions & 12 deletions docs/topics/release-process/policy.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,6 @@ scaffold_outputs = [
"dated_changelog_section",
"release_policy_boundary_block",
"release_notes_stub",
"release_boundary_test_stub",
"alpha_changelog_date_guard_entry",
"release_process_test_plan_rows",
]
steps = [
Expand Down Expand Up @@ -146,7 +144,7 @@ required_evidence = [

[release_notes.v0_2_0_alpha_1]
tag = "v0.2.0-alpha.1"
target_date = "2026-07-01"
target_date = "2026-06-21"
status = "published"
release_issue = 28
scope = [
Expand All @@ -166,7 +164,7 @@ non_goals = [

[release_notes.v0_3_0_alpha_1]
tag = "v0.3.0-alpha.1"
target_date = "2026-07-15"
target_date = "2026-06-24"
status = "published"
release_issue = 35
scope = [
Expand All @@ -191,7 +189,7 @@ non_goals = [

[release_notes.v0_4_0_alpha_1]
tag = "v0.4.0-alpha.1"
target_date = "2026-07-29"
target_date = "2026-06-25"
status = "published"
release_issue = 39
scope = [
Expand All @@ -213,7 +211,7 @@ non_goals = [

[release_notes.v0_5_0_alpha_1]
tag = "v0.5.0-alpha.1"
target_date = "2026-08-12"
target_date = "2026-06-25"
status = "published"
release_issue = 42
scope = [
Expand All @@ -240,7 +238,7 @@ non_goals = [

[release_notes.v0_6_0_alpha_1]
tag = "v0.6.0-alpha.1"
target_date = "2026-08-26"
target_date = "2026-06-26"
status = "published"
release_issue = 50
scope = [
Expand Down Expand Up @@ -271,7 +269,7 @@ non_goals = [

[release_notes.v0_7_0_alpha_1]
tag = "v0.7.0-alpha.1"
target_date = "2026-09-09"
target_date = "2026-06-27"
status = "published"
release_issue = 59
published_at = "2026-06-27T22:31:49Z"
Expand Down Expand Up @@ -316,7 +314,7 @@ non_goals = [

[release_notes.v0_8_0_alpha_1]
tag = "v0.8.0-alpha.1"
target_date = "2026-09-23"
target_date = "2026-06-28"
status = "published"
release_issue = 62
published_at = "2026-06-28T01:41:16Z"
Expand Down Expand Up @@ -365,7 +363,7 @@ non_goals = [

[release_notes.v0_9_0_alpha_1]
tag = "v0.9.0-alpha.1"
target_date = "2026-10-07"
target_date = "2026-06-28"
status = "published"
release_issue = 70
published_at = "2026-06-28T07:04:06Z"
Expand Down Expand Up @@ -407,7 +405,7 @@ non_goals = [

[release_notes.v0_10_0_alpha_1]
tag = "v0.10.0-alpha.1"
target_date = "2026-10-21"
target_date = "2026-06-29"
status = "published"
release_issue = 76
published_at = "2026-06-29T04:21:11Z"
Expand Down Expand Up @@ -446,7 +444,7 @@ non_goals = [

[release_notes.v0_11_0_alpha_1]
tag = "v0.11.0-alpha.1"
target_date = "2026-11-04"
target_date = "2026-06-30"

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Stop seeding the next release from the last tag date

Changing the final policy date to 2026-06-30 makes the unchanged next_release_target_date calculation scaffold 2026-07-14 for v0.12, which is already in the past as of 2026-08-04. That stale value is copied into the changelog, policy, and release notes, while release-dates cannot detect it until the tag exists, so the next release-prep branch passes pre-tag verification with a knowingly incorrect date. Release prep should accept or derive a current release date instead of adding 14 days to historical publication data.

Useful? React with 👍 / 👎.

status = "published"
release_issue = 109
published_at = "2026-06-30T07:58:29Z"
Expand Down
Loading
Loading