fls-changelog-verification

What I do

• Identify the diff range and spec files that changed in src/.
• Extract paragraph IDs added or removed in a diff and locate the :dp: IDs that own modified text.
• Check whether syntax categories, sections, or glossary entries changed and should be recorded.
• Provide a checklist to ensure src/changelog.rst has the right release entry and references (:p:, :s:, :t:, :ref:).

When to use me

• After editing spec text for a Rust release note item.
• When reviewing a PR that adds or fixes changelog entries.

Diff source variants

• Feature PR branch checked out: git diff main...HEAD -- src
• Changelog-only follow-up PR: diff the spec-change range git diff <spec-base>..<spec-head> -- src or inspect with gh pr diff <spec-pr> --repo rust-lang/fls
• Local WIP: git diff -- src (unstaged) and git diff --cached -- src (staged)

Workflow

1. Pick a base for the diff (default main...HEAD, or origin/main...HEAD if you have the remote).
2. List changed spec files:

git diff --name-only main...HEAD -- src

1. Collect new and removed paragraph IDs:

git diff --unified=0 main...HEAD -- src | rg '^[+]\s:dp:' git diff --unified=0 main...HEAD -- src | rg '^[-]\s:dp:'

1. Identify changed paragraphs with existing IDs:

- For each diff hunk, find the nearest :dp: above the change in the file and record that ID. - Use git diff --unified=3 main...HEAD -- src/path.rst and search in the file with rg -n ':dp:' src/path.rst. - Ignore wrap-only changes (same wording, same indentation, same roles). - Treat list-structure or indentation changes as meaningful, even if the wording is unchanged. - Treat role changes (e.g., :dt: -> :t:) as meaningful even when wording is the same.

1. Check for other changelog-worthy items:

- .. syntax:: blocks or grammar category names -> "New/Changed syntax" using :s:. - New section anchors (.. fls...:) -> "New section" using :ref:. - New glossary entries in src/glossary.rst -> "New glossary entry" using :t:.

1. Cross-check src/changelog.rst:

- Entry is under the correct "Language changes in Rust X.Y.Z". - Upstream PR link is present. - Lists of changed/new/removed paragraphs match the IDs you collected (:p:). - Removed IDs should not appear in changed/new lists. - "No change: ..." reason is present when appropriate.

Notes

• Prefer diffing the spec-change PR (not the changelog-only PR) to build the ID list.
• When comparing paragraphs, treat blank lines as paragraph boundaries to avoid false positives from surrounding structure changes.

Review comments

• Draft inline review comments in $OPENCODECONFIGDIR/reviews/<pr-number>/commentN.md.
• Add YAML front-matter with pr, file, linehint (right-side/new line in the PR diff), and linehint_side: new.
• Optionally include section and context to make the target location obvious.
• Use one file per inline location; include suggestion blocks when proposing exact edits.

References

• src/changelog.rst
• src/glossary.rst
• exts/ferrocene_spec/README.rst