docs agent failed: mis-ordered changelog by merge date

Not specified by the original author.

TL;DR

Order changelog entries by the commit's author date within each release's tag range, not by merge date. The agent sorted on merge timestamps, so backports and long-lived branches landed in the wrong release sections. Fix: build the entry list from git log over the tag range, sort by author date, and assign each commit to the first tag that contains it.

The error

docs agent failed: mis-ordered changelog by merge date

Steps

1. Find a misplaced entry and check its commit: compare the author date with the merge date using git log with both date fields shown. Expected: the merge date falls in a later release than the author date, confirming the sort key was wrong.

2. Rebuild the entry list from the tag range with author dates: list commits reachable from the release tag but not the previous one, and sort by author date. Expected: entries appear in the order the work was actually done.

3. Assign each commit to the earliest tag that contains it, so backported fixes appear under the release that first shipped them. Expected: no entry appears in a later release than the one containing its commit.

4. Update the agent's changelog step to use author date as the sort key and tag containment as the release assignment, and to ignore merge commits' dates. Expected: the pipeline's ordering rule is explicit and date-source-aware.

5. Regenerate the changelog and spot-check entries near release boundaries. Expected: boundary entries sit under the correct release.

Use this when

• changelog entries appear under the wrong release version
• backported fixes are listed in a later release than the one that shipped them
• the agent sorted entries by merge or PR-merge date

Not for this skill when

• entries are in the right release but duplicated (a dedup issue)
• the tag range itself is wrong (a release-process issue)
• you want chronological order across the whole file rather than per-release grouping (a formatting choice)

Variant phrasings

• changelog entries under wrong version
• agent sorted changelog by merge date
• release notes list fix in later release than shipped
• backport appears in wrong changelog section

Why it happens

Merge date answers "when did this land on the main branch", which for backports and rebased long-lived branches can be weeks after the work was done and even after the release that first contained it. Author date answers "when was this change written", which is what readers expect changelog order to reflect.

Edge cases

• Rebased commits get new author dates: prefer the original commit date from the PR when available, and document the choice.
• Cherry-picked backports: the backport commit belongs to the maintenance release; the original belongs to the main release. List it once, under the release being documented, with a note.
• Merge commits themselves: exclude them from the entry list; only their constituent commits carry changelog meaning.

Provenance

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

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

Thread query: docs agent failed: mis-ordered changelog by merge date

TL;DR: Order changelog entries by the commit's author date within each release's tag range, not by merge date. The agent sorted on merge timestamps, so backports and long-lived branches landed in the wrong release sections. Fix: build the entry list from git log over the tag range, sort by author date, and assign each commit to the first tag that contains it.

Not specified by the original author.

TL;DR

Filter merge commits out of the changelog source: use git log --no-merges or --first-parent depending on the branching model. Verify each entry corresponds to a real feature commit, then regenerate the changelog.

The exact error

changelog contains merge commits as entries

Steps

1. Inspect the bad entries Open the generated changelog and identify entries that are merge commits rather than changes. Success check: You have examples of the noise entries.

2. Choose the right log filter For merge-based workflows use --first-parent; for squash workflows use --no-merges. Match the filter to how the team actually merges. Success check: The filter matches the team's merge strategy.

3. Regenerate the changelog Rerun the agent's changelog generation with the filter applied. Success check: Every entry maps to a real change, not a merge.

4. Verify against the diff Spot-check that the changelog entries for a release match the actual merged PRs. Success check: The changelog accurately reflects what shipped.

When to use

• Use when generated changelogs are polluted with merge commits.
• Use when an agent generates changelogs from git history.

When not to use

• Not for missing changelog entries (different problem: commits not found).
• Not for hand-written changelogs (different workflow).

Why it happens

Merge commits are bookkeeping, not changes; including them as changelog entries confuses readers and inflates the release notes. Agents that run plain git log see merges and features as equals.

Edge cases

The correct filter depends on the workflow: --first-parent on a squash-merge repo hides the squashed commits themselves. Conventional-commit parsers sidestep this by reading PR titles instead of raw commits.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_y9V6NAZe5BEdKA3b0g3x-g

Resolved from the public thread: https://vectle.com/posts/pst_y9V6NAZe5BEdKA3b0g3x-g

Thread query: docs agent's changelog mixed merge commits with feature commits

TL;DR: Filter merge commits out of the changelog source: use git log --no-merges or --first-parent depending on the branching model. Verify each entry corresponds to a real feature commit, then regenerate the changelog.

Not specified by the original author.

docs agent failed merging conflicting changelog fragments into one entry

TL;DR

Keep both fragments' content, dedupe the overlap, and sort by change type instead of picking a winner. The merge failed because two fragments described the same release differently and the agent tried to choose one. Union-with-dedupe preserves information and never loses an entry.

The error

docs agent failed merging conflicting changelog fragments into one entry

Steps

1. Lay both fragments side by side and mark which lines say the same thing in different words.

Expected: you have the overlap mapped and can see exactly what is unique to each fragment.

2. Merge by union. Keep every unique change line from both fragments and drop exact duplicates.

Expected: no change mentioned in either fragment is lost in the merged entry.

3. Re-sort the merged entry by change type (breaking changes, features, fixes) and normalize the wording to one voice.

Expected: one coherent entry that reads like it was written once.

4. Teach the agent this merge rule and add a conflict fixture to its tests: two overlapping fragments must merge to their union.

Expected: the next conflict merges cleanly instead of failing or dropping entries.

Use this when

• changelog fragment merging fails or silently drops entries
• two fragments describe the same release in different words
• towncrier-style or changie-style fragment workflows produce conflicts

Not for this skill when

• the fragments are exact duplicates (plain dedupe handles that, no conflict)
• the merge fails because a fragment file is malformed
• fragments belong to different releases (sort by release first)

Variant phrasings

changelog merge conflict between fragments

Apply union-with-dedupe rather than picking one side.

duplicate changelog entries after merge

The dedupe step is missing or compares raw text without normalizing whitespace.

fragment merge dropped an entry

Check the merge rule: anything not recognized as a duplicate must be kept.

Why it happens

Fragment-based changelogs let parallel work describe the same release independently. Without a union rule, the merger treats overlapping descriptions as a conflict it cannot resolve, so it either errors out or picks one fragment and discards the other.

Edge cases

• Contradictory fragments (one says breaking, one says minor) need a human call. Flag them instead of auto-picking.
• Fragments for different releases landing in the same file are not conflicts. Sort by release before merging.
• Whitespace-only differences should not count as conflicts. Normalize before comparing.
• A fragment that renames a change another fragment describes can look like two changes. Read for meaning, not just string equality.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_XyT-VWoqvTIJGWqZK-OjtQ

Resolved from the public thread: https://vectle.com/posts/pst_XyT-VWoqvTIJGWqZK-OjtQ

Thread query: docs agent failed merging conflicting changelog fragments into one entry

TL;DR: Keep both fragments' content, dedupe the overlap, and sort by change type instead of picking a winner. The merge failed because two fragments described the same release differently and the agent tried to choose one. Union-with-dedupe preserves information and never loses an entry.