otel-changelog-pr-verifier

name	otel-changelog-pr-verifier
description	Verify whether CHANGELOG entries in an OpenTelemetry Go repository point to the correct pull requests and whether each `(#NNNN)` matches the described change. Use when checking a release PR, validating a CHANGELOG section, or screening only mismatched changelog-to-PR references.
metadata	{"name":"OTel Changelog PR Verifier","description":"Verify changelog PR numbers in OpenTelemetry Go release work.","author":"Flc","created":"2026-04-03T04:32:49.000Z"}

OTel Changelog PR Verifier

Verify CHANGELOG.md entries in an OpenTelemetry Go repository against the referenced GitHub pull requests.

Operating Mode

Prioritize:

• exact PR-to-entry matching before prose quality
• the release section under review, not the entire changelog
• concrete mismatches only
• local repository evidence first, GitHub metadata second

Do not flood the user with entries that are already correct.

Execution Assumption

Assume the user has provided a concrete target PR, usually as a PR number or PR URL in the current repository.

The default example repository is open-telemetry/opentelemetry-go, but the same workflow applies to similar OpenTelemetry Go repositories when the task is already anchored to a specific repository and PR.

Workflow

1. Check out the target PR locally

Prefer:

gh pr checkout <pr-number>
git status --short --branch
gh pr view <pr-number> --json baseRefName

If the local checkout is not already anchored to the target repository, use an explicit repo selector:

gh pr checkout <pr-number> -R <owner/repo>
git remote -v
gh pr view <pr-number> -R <owner/repo> --json baseRefName

If gh cannot reach GitHub because of sandbox restrictions, request escalation and retry.

Detect the PR base branch from GitHub metadata and use origin/<base-branch> for diffs instead of assuming main.

For concrete command patterns and output templates, see references/workflow.md.

2. Isolate the release section under review

Read only the relevant CHANGELOG.md block, usually the newest released section above the previous release.

Prefer commands such as:

git diff origin/<base-branch>...HEAD -- CHANGELOG.md
nl -ba CHANGELOG.md | sed -n '<start>,<end>p'
awk '/^## \[<release>\]/{flag=1;print;next}/^## \[<previous-release>\]/{flag=0}flag' CHANGELOG.md

If the user only cares about entries introduced by the release PR, review only that released section.

3. Extract the referenced PR numbers

Collect unique #NNNN values from the target section.

Prefer:

awk '/^## \[<release>\]/{flag=1;next}/^## \[<previous-release>\]/{flag=0}flag' CHANGELOG.md | rg -o '#[0-9]+' -N | sort -u

4. Fetch PR metadata from GitHub

Use gh pr view for each referenced number.

Prefer:

gh pr view <number> --json number,title,url,state,mergedAt

If the current repository context is not already clear, make the repository explicit:

gh pr view <number> -R <owner/repo> --json number,title,url,state,mergedAt

If needed, batch with a shell loop. Request escalation if network access is blocked.

5. Compare changelog text to PR metadata

For each entry, verify:

• the PR number resolves to the expected GitHub PR
• the PR title and changed area are consistent with the changelog description
• the entry is not obviously pointing at the wrong PR

Treat these as mismatches:

• changelog description refers to a different feature or package than the PR
• PR number resolves to a different topic than the entry text
• entry claims a fix/addition that is not plausibly what the PR did

Do not flag harmless wording differences if the referenced PR is clearly the same change.

When deciding whether wording is "close enough", use the matching heuristics in references/workflow.md.

6. Report only the incorrect items

Default output:

No incorrect entries found.

If mismatches exist, return a compact list:

- CHANGELOG line <line>: `<entry text>` uses `#<number>`, but PR title is `<title>`.
  Correct PR: <if known>
  PR URL: <url>

Review Rules

• Prefer the actual release section over guessing from the diff summary.
• Use exact line references when reporting problems.
• If all entries are consistent, say so directly.
• Keep the answer focused on incorrect references; a full mapping table is optional and only on request.