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.

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