Situation

Currently, all changes are recorded in a single CHANGELOG.rst file. In most cases this is enough and it works well.

However, in some cases conflicts can occur. Sometimes it would be helpful to have a tool which could create that changelog automatically.

Idea

Some projects use the towncrier tool. It is built around "news fragments", little text snippets that are stored in different files under a common directory (e.g. changes.d). When a new release is drafted, these files are brought together and create the final changelog file. This minimizes any conflicts.

Every filename contains an issue number and a "type". A type can be feature, bugfix, doc, removal, or you can use self-defined types. These types will become sections in the final changelog file. All fragments are collected, sorted, and added under the sections.

When Towncrier is correctly set up, a typical workflow looks like this:

1. Start working on a specific issue, let's say, 123.
2. Decide what type this issue is, for example, feature, bugfix, etc.
3. Combine the two information and create a fragment file: towncrier create 123.bugfix.
   This file will be added inside the changes.d directory.
4. Describe the issue.
5. Commit the file.
6. Merge issue to master.

The more issues you solve, the more files you will collect inside your changes.d directory. At some point, we need to create a new release. In this case, the workflow looks like this:

1. Create a new release branch.
   (could be done in other ways too, but this makes things a bit easier).
2. Raise the version.
3. Produce a draft changelog to see everything is included with: towncrier build --draft.
4. If satisfied, produce the final changelog file with: towncrier build.
   This command will remove all files inside the changes.d directory and create the final changelog file.
5. Commit all changes and merge it.

Pros

• All changes reside in single files under a common directory, for example, changes.d.
  This makes it easier to see which will end up in the new release.
• Reduces conflicts as changes are stored in separate files.
• Able to configure

Cons

• Works on Python 3.5+ only.
  (This may be not as a big disadvantage as we move to Python 3 soon.)
• Every file has to be named with ISSUE-TYPE. This may not always appropriate.
• Towncrier works best in a development system where all merges involve closing a ticket.

@python-semver/reviewers @tlaferriere what do you think about that? Would that be helpful or just too much?