Skip to content

Adopt a conflict-free CHANGELOG workflow for parallel PRs #189

Description

@DocGerd

Problem

The current changelog ritual (#131) has every user-visible-behavior PR add an entry to CHANGELOG.md's single [Unreleased] section. This repo routinely develops several PRs in parallel (parallel implementer agents). When 2+ of those each edit the same [Unreleased] region, they conflict — a merge conflict, or a forced re-sync collision under the strict up-to-date policy on develop.

(Config/tooling/docs-only PRs correctly get no changelog entry, so they don't contribute to this — the conflict is specifically between multiple user-visible-behavior PRs.)

Options (pick one)

  1. Changelog fragments — recommended, industry best practice. Each PR adds a small, uniquely-named file under changelog.d/ (e.g. changelog.d/165.fixed.md) and never edits CHANGELOG.md directly, so two PRs never touch the same file → zero conflicts. A release step (towncrier / changesets / a tiny local script) assembles fragments into the release section at cut time and deletes them. Atomic with each PR and conflict-free.
  2. Interim rule, no tooling. Until fragments land: when 2+ PRs run in parallel, do NOT have each edit CHANGELOG.md. Add the entry only in the last PR of the batch, or open a single dedicated changelog PR at batch/session end. A solo PR may keep its atomic entry (no conflict possible).

Acceptance criteria

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: toolingRepo config, Claude automation, CI/CD metapriority: mediumPlanned, not urgenttype: choreTooling, deps, refactor, repo maintenance

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions