Requested Feature

The current workflow for maintaining Sopel's NEWS file involves a lot of human labor, a lot of which is associated with writing changelog text that goes with each changeset.

I propose to introduce a workflow for maintaining the NEWS file using a "fragments" workflow like the one used by CPython.

The basic idea is that each PR includes a "fragment" file that lists entries to be added to the changelog, and at release time, these fragments are automatically gathered into a new changelog entry.

I am personally a fan of the tool scriv for its simplicity and flexibility, and intend to submit a PR based upon it, but there are other tools that implement a similar fragments-based workflow, e.g. towncrier and setuptools-changelog.

Problems Solved

This approach spreads the cost of maintaining the changelog across all changesets, and encourages PR authors to summarize their own work in a human-readable fashion.

This workflow also allows changesets to list changes in multiple sections of the changelog. For example, a PR may include changes that affect both the core details of Sopel and public-facing API. This is technically possible with the current manual authoring of the changelog, but it seems that the most common realization is that we choose one category or another for each such changeset.

It is also easy to check using CI that a changeset includes a fragment file. Most workflows I have seen allow bypassing this requirement using a specific NO NEWS REQUIRED label or similar.

Alternatives

• Continue to manually collate and edit the changelog.
  • Requires human effort at release time, proportional to the size of a release
• Have changesets edit the changelog directly.
  • Creates a confusing historical record of changes by modifying the changelog before a release happens.
• Generate the changelog automatically from commit messages (using e.g. git-chglog)
  • Requires more human attention to commit message format than status quo, has lacking granularity (i.e. a commit that includes multiple kinds of changes), and shoves more metadata into commit messages.

Notes

No response