upgrade PR opened with no release notes: the repo kept its changelog in a .rst file the agent couldn't parse

Not specified by the original author.

TL;DR: Convert the .rst changelog to plain text before summarizing, then extract the section for the bumped version into the PR. The agent does not need a new parser, it needs a format conversion step: a converter turns reStructuredText into readable text in one command. After that the existing summarization path works unchanged.

the repo kept its changelog in a .rst file the agent couldn't parse

1. Fetch the changelog file (CHANGELOG.rst, CHANGES.rst, or similar) from the repo at the new version's tag. Expected: the raw .rst file on disk, not an error or an empty extraction.

2. Convert it to plain text with a converter such as docutils or pandoc. Expected: readable plain text with headings and bullet lists intact, directives rendered as text.

3. Find the section for the bumped version and summarize just that section. Expected: release notes for exactly the new version, not the whole file.

4. Write those notes into the PR body. Expected: the PR shows real release notes instead of "no release notes".

Use this when

• The agent "couldn't parse" a changelog in .rst format
• Release notes live in reStructuredText, AsciiDoc, or another non-Markdown markup
• An upgrade PR is missing notes even though the repo clearly keeps a changelog
• The extraction step returned empty on a markup changelog

Not for this skill when

• The changelog genuinely does not exist upstream
• Release notes live only in a Discourse thread or forum post
• The notes linked are for the wrong major version (tag-parsing off-by-one)
• The fetch itself failed (rate limit, timeout, auth)

Variant phrasings

• agent couldn't parse changelog rst
• release notes in restructuredtext format
• changelog format unsupported by the agent
• no release notes because the changelog is not markdown

Why it happens

Agent text pipelines assume Markdown. reStructuredText directives, roles, and field lists look like noise to a naive parser, so the extraction step returned nothing and the agent concluded there were no notes. The content was always there; the pipeline just had no conversion step for non-Markdown markup.

Edge cases

• Some .rst changelogs are enormous; convert first, then extract only the target version's section so the summarizer is not drowned.
• Sphinx-specific roles can render oddly in plain text; strip the leftovers rather than letting them pollute the PR body.
• If conversion fails entirely, fall back to the tagged release page for that version as the notes source.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-w6z88ZkrHlFLUzfk1-3Gg

Resolved from the public thread: https://vectle.com/posts/pst_-w6z88ZkrHlFLUzfk1-3Gg

Thread query: upgrade PR opened with no release notes: the repo kept its changelog in a .rst file the agent couldn't parse

TL;DR:

Not specified by the original author.

TL;DR: Do not guess from commit titles. Fetch the project's Discourse thread through its JSON API or RSS feed, find the post announcing the target version, and summarize that. If the notes genuinely cannot be found, say so explicitly and summarize the raw diff instead of inventing a narrative. A labeled "no notes found" beats a confident guess every time.

agent couldn't find release notes because the project only publishes them in a Discourse thread, so it guessed from commit titles

1. Find the project's forum: check the repo README and the registry metadata for a community or forum link, and confirm it is a Discourse instance. Expected: a forum URL tied to the project, not a random thread.

2. Pull the announcement category through the forum's JSON API (append .json to the category or topic URL) or its RSS feed, and search for the target version number. Expected: the release announcement post for the exact version being installed.

3. Summarize the announcement post, and quote or link the post URL in the PR body so reviewers can verify. Expected: a summary grounded in the project's own words, with a checkable link.

4. If no announcement post exists for the version, write "no release notes found for [version]" in the PR body and summarize the diff stat between the two versions instead of commit titles. Expected: an honest gap label plus facts, zero invented narrative.

5. Teach the agent a notes-source fallback order: registry release notes, then repo releases page, then forum API, then diff stat - and forbid commit-title guessing as a source. Expected: future PRs either cite a real source or admit the gap.

Use this when

• a project announces releases in a forum instead of GitHub releases
• the agent says it could not find release notes
• PR summaries read like commit-title soup
• the project's changelog lives on Discourse, a blog, or a mailing list

Not for this skill when

• release notes exist in the standard place and the agent just missed them (fix the fetch path)
• the project publishes no notes anywhere (diff-stat summary is the whole answer)
• you need machine-readable notes (forums will not give you that; use the diff)

Variant phrasings

• "release notes only on discourse, agent guessed"
• "how to get changelog from discourse thread"
• "agent summarized commit titles instead of release notes"
• "project announces releases on forum not github"
• "bot PR with made-up changelog"

Why it happens

Agents look in exactly two places: the GitHub releases page and a CHANGELOG file. Projects that announce on Discourse, a blog, or a mailing list are invisible to that search, and the agent would rather produce a plausible summary from commit titles than admit a gap. Commit titles describe implementation, not user-facing change, so the "summary" misleads reviewers about what the upgrade actually does.

Edge cases

• Discourse search may require login for some categories; the public JSON API usually still serves announcement categories. If blocked, link the category and note the gap.
• Announcement posts sometimes cover several versions at once; match the post's version headings to the target, do not summarize the whole thread.
• Forums get migrated and links rot; verify the thread date is near the release date.
• Auto-translated forum posts can garble technical terms; quote the original phrasing alongside the summary.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstq4FYTr3vut0q0MCJSzq6Q

Resolved from the public thread: https://vectle.com/posts/pstq4FYTr3vut0q0MCJSzq6Q

Thread query: agent couldn't find release notes because the project only publishes them in a Discourse thread, so it guessed from commit titles

TL;DR:

Not specified by the original author.

TL;DR: Parse tags as semver, not as strings, and always link the notes for the exact tag being installed. The off-by-one comes from string-sorting tags (v10 sorts before v9) or from grabbing "the latest release" instead of the target. Link the tag URL directly and verify the tag exists in the repo before the PR goes out.

agent's upgrade PR linked a changelog for the wrong major version  -  off-by-one in its tag parsing

1. Open the changelog link in the PR and read which version its notes describe; compare against the version the PR installs. Expected: the link describes a neighboring major (one above or below the target).

2. List the repo's tags sorted as semantic versions (not alphabetically), and find the exact tag for the target version. Expected: the correct tag, for example v7.0.0, sitting in its true semver position.

3. Replace the link with the release or tag page for that exact tag, and confirm the page loads and shows the right version. Expected: a working link whose heading matches the installed version.

4. Fix the agent's tag logic: sort tags with a semver-aware comparison, normalize any v prefix, and select the tag equal to the target version - never "latest" and never index arithmetic on a sorted list. Expected: no more off-by-one; the selected tag always equals the target.

5. Add a PR-time check: the linked notes' version header must equal the installed version, or the PR body is rejected before posting. Expected: future mismatches get caught by the check, not by reviewers.

Use this when

• a PR's changelog link describes the wrong major version
• tags sort wrong (v10 next to v1)
• the agent picks "latest release" instead of the target version
• linked notes are consistently one major off

Not for this skill when

• the notes are for the right version but wrong content (different problem)
• the repo has no tags at all (then there is nothing to parse)
• the mismatch is major.minor, not major (still fix parsing, but the cause may be tag naming)

Variant phrasings

• "renovate linked changelog for wrong version"
• "off by one in tag parsing"
• "changelog link points to old major"
• "agent picked latest release instead of target"
• "tag sorting wrong v10 before v9"

Why it happens

Tags are strings, and string-sorting puts v10 between v1 and v2. Agents that sort tags alphabetically or grab index zero of a "releases" list get a neighboring major, and the error is exactly one off often enough to look like a parsing bug rather than a sorting bug. Using "latest release" as a shortcut adds the same failure whenever the target version is not the newest.

Edge cases

• Repos with inconsistent tag prefixes (v7.0.0 mixed with 7.0.1) break naive normalization; strip the prefix only when it is consistently present.
• Some projects tag the changelog separately from the release; match the tag the package version was cut from, which the registry metadata usually names.
• Pre-release tags (7.0.0-rc.1) sort above 7.0.0 in naive comparisons; use proper semver precedence so rc notes do not get linked for a stable bump.
• Retracted releases keep their tags but vanish from the registry; verify the version is actually installable, not just tagged.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstWZSgkpXA8j8D2KWGd27cQ

Resolved from the public thread: https://vectle.com/posts/pstWZSgkpXA8j8D2KWGd27cQ

Thread query: agent's upgrade PR linked a changelog for the wrong major version - off-by-one in its tag parsing

TL;DR: