[GH-ISSUE #3058] [Docs] Release guide still names the 6.2 candidate in its compatibility review step #1073

New issue

Closed

opened 2026-10-15 18:30:50 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:30:50 +00:00

Owner

Originally created by @coygeek on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3058

Before submitting

I searched the existing issues for a related documentation report.
I removed credentials, tokens, private paths, and sensitive target data.

Documentation location

docs/releasing.md#compatibility-and-version-selection (first paragraph of the section)

Problem

The "Compatibility and version selection" section of docs/releasing.md opens with a step fixed to one past release: "For the 6.2 candidate, review the 6.1 to 6.2 migration guide alongside the changelog before publication." In the source, "6.1 to 6.2 migration guide" links to migration-6.2.md. REA has since published 6.3.0 (2026-10-09) and 6.4.0 (2026-10-11), and both CHANGELOG.md entries have a "BREAKING CHANGES" section. A maintainer preparing the next release therefore reads a compatibility step that names an already-published candidate and the migration guide for an older version pair. The open Release Please PR #1693 currently proposes rea-agents 6.5.0, the release this step would now apply to.

This affects maintainers who follow the release procedure; CONTRIBUTING.md sends them there ("Use the release guide"). It is wording only and changes no product behavior.

Expected content

The compatibility step should apply to the release being prepared, either as guidance that holds for any release or by naming the release under preparation, rather than presenting the 6.2 candidate as the current review. The next paragraph of the same section already gives version-independent guidance (the always-bump-minor strategy, no compatibility promise from a minor increment, and review of the changelog's breaking-change section and migration notes); that guidance should remain. Links to the 6.1 to 6.2 guide can stay where they are presented as history.

Supporting evidence

Checked on 2026-10-13 on the latest release, rea-agents 6.4.0 (tag rea-agents-6.4.0, commit a56f7bb668ab23fec8d33f7af353ac7ed2fe1895), and on main at commit e049ef70f71aeb9965e9d75d4d4a84ea02eaee11, from a fresh shallow clone of main and the tag contents through the GitHub API (compare URLs in the CHANGELOG.md headings elided):

$ grep -n "6.2 candidate" docs/releasing.md        # main
87:For the 6.2 candidate, review the [6.1 to 6.2 migration guide](migration-6.2.md)
$ grep -n "6.2 candidate" docs/releasing.md        # rea-agents-6.4.0
84:For the 6.2 candidate, review the [6.1 to 6.2 migration guide](migration-6.2.md)
$ grep -n "^## \[6\.[2-4]" CHANGELOG.md            # rea-agents-6.4.0
3:## [6.4.0](...) (2026-10-11)
67:## [6.3.0](...) (2026-10-09)
235:## [6.2.0](...) (2026-10-09)

docs/ on main contains no migration guide other than migration-6.2.md. The sentence was added by #1304 (commit c267e9922751c03df312655ebd623de1b480215c, 2026-10-09 15:31 UTC), about 80 minutes before the 6.2.0 release was published at 16:51 UTC, as a pre-release step for that candidate. docs/releasing.md has been edited four more times since (most recently on 2026-10-13) without changing it. Elsewhere the 6.2 guide is presented as history: docs/index.md says the 6.2 migration "records that release's compatibility changes".

No open pull request changes this sentence: the open PRs that touch docs/releasing.md (#2052, #2815, #3003) leave it unchanged.

Additional context

Searched open and closed issues and pull requests for "6.2 candidate", migration-6.2 and releasing.md; none reports this sentence. The English documentation audit in #2156 does not list it. Severity estimate: cosmetic (stale maintainer wording); the workaround is to follow the section's next paragraph and review the changelog's breaking-change section for the release being prepared.

Originally created by @coygeek on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3058 ### Before submitting - [x] I searched the existing issues for a related documentation report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Documentation location `docs/releasing.md#compatibility-and-version-selection` (first paragraph of the section) ### Problem The "Compatibility and version selection" section of `docs/releasing.md` opens with a step fixed to one past release: "For the 6.2 candidate, review the 6.1 to 6.2 migration guide alongside the changelog before publication." In the source, "6.1 to 6.2 migration guide" links to `migration-6.2.md`. REA has since published 6.3.0 (2026-10-09) and 6.4.0 (2026-10-11), and both `CHANGELOG.md` entries have a "BREAKING CHANGES" section. A maintainer preparing the next release therefore reads a compatibility step that names an already-published candidate and the migration guide for an older version pair. The open Release Please PR #1693 currently proposes `rea-agents` 6.5.0, the release this step would now apply to. This affects maintainers who follow the release procedure; `CONTRIBUTING.md` sends them there ("Use the release guide"). It is wording only and changes no product behavior. ### Expected content The compatibility step should apply to the release being prepared, either as guidance that holds for any release or by naming the release under preparation, rather than presenting the 6.2 candidate as the current review. The next paragraph of the same section already gives version-independent guidance (the `always-bump-minor` strategy, no compatibility promise from a minor increment, and review of the changelog's breaking-change section and migration notes); that guidance should remain. Links to the 6.1 to 6.2 guide can stay where they are presented as history. ### Supporting evidence Checked on 2026-10-13 on the latest release, `rea-agents` 6.4.0 (tag `rea-agents-6.4.0`, commit `a56f7bb668ab23fec8d33f7af353ac7ed2fe1895`), and on `main` at commit `e049ef70f71aeb9965e9d75d4d4a84ea02eaee11`, from a fresh shallow clone of `main` and the tag contents through the GitHub API (compare URLs in the `CHANGELOG.md` headings elided): ```text $ grep -n "6.2 candidate" docs/releasing.md # main 87:For the 6.2 candidate, review the [6.1 to 6.2 migration guide](migration-6.2.md) $ grep -n "6.2 candidate" docs/releasing.md # rea-agents-6.4.0 84:For the 6.2 candidate, review the [6.1 to 6.2 migration guide](migration-6.2.md) $ grep -n "^## \[6\.[2-4]" CHANGELOG.md # rea-agents-6.4.0 3:## [6.4.0](...) (2026-10-11) 67:## [6.3.0](...) (2026-10-09) 235:## [6.2.0](...) (2026-10-09) ``` `docs/` on `main` contains no migration guide other than `migration-6.2.md`. The sentence was added by #1304 (commit `c267e9922751c03df312655ebd623de1b480215c`, 2026-10-09 15:31 UTC), about 80 minutes before the 6.2.0 release was published at 16:51 UTC, as a pre-release step for that candidate. `docs/releasing.md` has been edited four more times since (most recently on 2026-10-13) without changing it. Elsewhere the 6.2 guide is presented as history: `docs/index.md` says the 6.2 migration "records that release's compatibility changes". No open pull request changes this sentence: the open PRs that touch `docs/releasing.md` (#2052, #2815, #3003) leave it unchanged. ### Additional context Searched open and closed issues and pull requests for "6.2 candidate", `migration-6.2` and `releasing.md`; none reports this sentence. The English documentation audit in #2156 does not list it. Severity estimate: cosmetic (stale maintainer wording); the workaround is to follow the section's next paragraph and review the changelog's breaking-change section for the release being prepared.

bsakaguchi

2026-10-15 18:30:50 +00:00

closed this issue
added the
documentation
label

bsakaguchi commented

2026-10-15 18:30:52 +00:00

Author

Owner

@L00PLeGeNd commented on GitHub (Oct 14, 2026):

Claiming this docs fix.

Plan: rewrite the compatibility-review step in docs/releasing.md so it applies to the release under preparation (version-agnostic), while keeping the existing 6.1→6.2 migration guide as historical reference. No product behavior changes.

PR shortly.

@L00PLeGeNd commented on GitHub (Oct 14, 2026): Claiming this docs fix. Plan: rewrite the compatibility-review step in `docs/releasing.md` so it applies to the release under preparation (version-agnostic), while keeping the existing 6.1→6.2 migration guide as historical reference. No product behavior changes. PR shortly.

bsakaguchi referenced this issue

2026-10-15 18:31:35 +00:00

[GH-ISSUE #3219] [Bug] Non-canonical Evidence bundles are reported as unreadable ledger output #1157

bsakaguchi referenced this issue

2026-10-17 21:08:19 +00:00

[PR #1073] [MERGED] fix(evidence): name the failed constraint when a bundle is rejected #2622

bsakaguchi referenced this issue

2026-10-31 00:42:30 +00:00

[GH-ISSUE #5957] [Bug] Process capture parsing drops structural issues when a semantic issue is present #3626