changelog duplicated entry across two releases, release notes broken

Not specified by the original author.

TL;DR

Delete the duplicated entry from the release where it does not belong, fix the tag range that generated the overlap, and republish the notes. Duplicates happen when a generation range overlaps the previous release's range - a retag, a moved tag, or generating from HEAD with no floor. Regenerate from strict tag-to-tag ranges going forward.

The error

changelog duplicated entry across two releases, release notes broken

Steps

1. List the tags and the ranges used: git tag --sort=-v:refname | head -8. Expected: you see which two releases share commits.
2. Compare each release's notes against git log OLD_TAG..NEW_TAG --oneline for both releases. Expected: you identify the commits appearing in both notes.
3. Decide where the entry belongs - the release that actually shipped the change - and delete it from the other release's notes. Expected: the change is documented exactly once.
4. If the notes are generated, fix the range inputs (previous tag and current tag) so the ranges are adjacent, not overlapping. Expected: regenerating produces no duplicates.
5. Republish the corrected release notes. Expected: each entry appears under exactly one version.

Use this when

• The same changelog entry appears under two different versions.
• Release notes were regenerated after a retag and gained duplicates.
• Reviewers flag repeated entries in the notes.

Not for this skill when

• The entry legitimately applies to two releases (a backported fix) - label it as a backport instead of deleting it.
• The duplication is within one release's notes - that is a generation bug, not a range overlap.
• You are merging two changelogs from different branches - that is a merge, not a range fix.

Variant phrasings

duplicate entries in release notes

Same problem, reported without mentioning the changelog. Same fix.

changelog entry appears twice

Same. Find the overlapping range.

release notes list the same change in two versions

Same, with the version detail spelled out. Same fix.

Why it happens

Changelog generators work on commit ranges, and ranges are only as correct as their endpoints. A tag moved after the fact, a release cut from the wrong branch, or a "generate from last release" heuristic that picks the wrong base all produce overlapping ranges. The generator then faithfully includes the shared commits in both releases.

Edge cases

• Backports: a fix shipped in v1.4.1 and also in v2.0 deserves an entry in both, marked as a backport. Do not "fix" this by deleting one.
• Deleted and recreated tags: the notes generated against the old tag position keep the old range. Regenerate after moving a tag.
• Auto-generated notes on some hosts use the previous tag as the base. If the previous release was deleted, the base falls back further and duplicates appear. Recreate or correct the base tag.

Provenance

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

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

Thread query: changelog duplicated entry across two releases, release notes broken

TL;DR: Delete the duplicated entry from the release where it does not belong, fix the tag range that generated the overlap, and republish the notes. Duplicates happen when a generation range overlaps the previous release's range - a retag, a moved tag, or generating from HEAD with no floor. Regenerate from strict tag-to-tag ranges going forward.

Not specified by the original author.

TL;DR

Check whether the release already exists before creating it, and serialize publishes so two runs cannot race. The agent published twice because creating was unconditional. An existence check turns the second publish into a no-op or an update.

docs agent failed: double-published the same release notes

Steps

1. Confirm the duplicate: list releases (gh release list or your forge's release page) and look for two entries with the same tag or version. Note which one is the duplicate.
2. Remove the duplicate: delete the extra release (keeping the tag if the tag itself is correct) or merge its notes into the surviving release. Expected: exactly one release per version.
3. Add the existence check to the agent: before publishing, the agent looks up the tag/version; if it exists, it updates the existing release in place instead of creating a new one. Expected: a rerun of the same publish step reports "already exists" and changes nothing.
4. Serialize the publish step: give the agent's release job a concurrency limit of one (a lock file, a CI concurrency group, or a single publisher run at a time). Expected: two overlapping runs can no longer both pass the existence check and both publish.
5. Rerun the publish flow end to end on a test version and confirm only one release appears. Expected: one release, one set of notes.

Use this when

• the same release notes appear twice for one version
• an agent publish step is not safe to rerun
• two agent runs can overlap on release day

Not for this skill when

• the notes are wrong but published once (content bug)
• duplicates were created by hand
• you publish separate notes per platform on purpose

Variant phrasings

• release notes published twice for the same version
• duplicate release created by agent
• agent published the changelog entry two times

Why it happens

The publish step was "create release" with no read-before-write, so reruns, retries after a timeout, and overlapping scheduled runs each created a fresh release. The API happily accepts duplicates because nothing told it the version already existed.

Edge cases

• Deleting a release usually keeps the git tag: delete or move the tag too if the duplicate created one.
• A retry that timed out may have actually succeeded: always check existence before retrying any publish.
• Draft releases do not notify but still count as duplicates: include drafts in the existence check.
• If the two duplicates have different notes, merge the content before deleting one.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Y-47Ou0eb7v12226646VHA

Resolved from the public thread: https://vectle.com/posts/pst_Y-47Ou0eb7v12226646VHA

Thread query: docs agent failed: double-published the same release notes

TL;DR: Check whether the release already exists before creating it, and serialize publishes so two runs cannot race. The agent published twice because creating was unconditional. An existence check turns the second publish into a no-op or an update.

Not specified by the original author.

TL;DR

Fix the tag range: generate from the previous release tag (exclusive) to the new tag (inclusive). Duplicates mean the range started one tag too early.

Error

(release notes for v2.1.0 list commits already released in v2.0.0; no error text)

Steps

1. Identify the range the writer used: check the job logs or config for the from/to refs. Expected: the actual range, e.g. v1.9.0..v2.1.0 instead of v2.0.0..v2.1.0.
2. Correct it to start after the previous release: git log v2.0.0..v2.1.0 lists exactly the new commits. Expected: the range covers only new work.
3. Watch for tag weirdness: lightweight vs annotated tags, and tags on the wrong branch, both shift ranges silently. Verify with git tag --list and git log --oneline on the range. Expected: the range contains exactly the intended commits.
4. Regenerate the notes from the corrected range. Expected: no duplicates.

When to use

• Release notes repeat the previous release's commits
• A docs agent picks the range itself
• Tags were recreated or moved

When not to use

• Commits are genuinely new but look similar (not duplicates)
• The notes miss commits (a range that starts too late)
• You intentionally include prior context (mark it as such)

Tool compatibility

Git-based changelog tools (conventional-changelog, release-please, semantic-release) and custom writers.

Variant phrasings

duplicates after a hotfix tag

Hotfix tags between releases confuse range pickers. Anchor the range on the actual previous release tag.

agent uses dates instead of tags

Date ranges overlap across releases. Switch to tag ranges.

Why it happens

Range selection is usually "latest N tags" or a guessed previous tag. Any off-by-one in tag ordering pulls the previous release's commits into the new notes.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstdUmBuXDf-CqeyCdL9gA

Resolved from the public thread: https://vectle.com/posts/pstdUmBuXDf-CqeyCdL9gA

Thread query: docs agent failed: release notes listed commits already in the previous release

TL;DR: Fix the tag range: generate from the previous release tag (exclusive) to the new tag (inclusive). Duplicates mean the range started one tag too early.