Use Towncrier for Changelog?

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?

[tlaferriere]

The only issue that I found is, when you do not have an issue, but you want to record the change.

If that change is worth recording, maybe it is also worth creating an issue for 😉.

You mean, we should separate the issue from a new issue which is only related to the fragment?

I meant that each pull request (change effected) should close at least one issue. For example, take the first PR I did on this repo: I just coded the changes, didn’t bother actually creating an issue to discuss goals beforehand. In this case, if we were using towncrier, a part of getting this PR accepted would have been to open an issue and link it in towncrier and in the PR. As for splitting off issues from another issue, I think this has more to do with what we consider to be in the scope of said issue (see the first sentence of this comment).

I think that having an issue for each changelog entry would make us more aware of what is actually changing, and it would encourage discussion on changes that could actually affect the users.

While we’re at it, I have to say that I like the projects feature for repos and I think we should use it more (e.g for feature releases). I think it’s a nice visual for tracking progress on related topics.

[tomschr]

I think, that is closed with #290 and commit cbd4335f