Feedback

[Kixunil]

You asked for feedback on Reddit but it better for me to send via GH, hope it's OK.

It's not clear what your crate does from the documentation. I have some practical experience with contributing to repositories with unfortunate changelog implementations. I wrote down my thoughts with proposed solution here: https://gist.github.com/Kixunil/f796f65500c4ca18ca629daaf2eca272

The person I wrote about there bailed, so feel free to get inspired or even implement it as specified. Would love to use it.

[matthiasbeyer]

Thanks for providing feedback, it is highly appreciated! I will fill my ideas into some issues!

[reivilibre]

Also going to provide some feedback here.

We use https://github.com/twisted/towncrier on Synapse quite successfully; the workflow is that each PR has a <PR number>.<PR type> 'changelog fragment' file created in changelog.d.
When we make a new release, we use towncrier to generate the segment of changelog since the last release and add it to the top of the changelog. What I find very useful is that:

• the changelog entries are sorted into different groups (features, bugfixes, removals, documentation changes, 'misc'/internal changes), which I think makes it easier for users to see what will affect them most of all
• the changelog entries link back to the PR that led to them, which is really useful for getting back to the code changes for a particular entry
• multiple PRs with the same changelog entry are collapsed into one entry, but links to all the PRs — reducing changelog spam/noise but still being useful for linking back to all the PRs

For some of our much smaller projects, we seem to have decided that this is too much faff and we don't bother ...
One especially annoying part is that you need to predict your PR number before opening the PR, or open the PR first of all. Some of us have a script to create the changelog file, which gets the latest PR number and adds 1... but otherwise this system is rather useful for us.

(I think some projects use issue tracker numbers rather than PR numbers for the changelog fragments.)

It's not a perfect system but I thought it would just be worth leaving a note here for reference/inspiration ...