Generating the Release Notes
Generating the Release Notes is an Art. We need to summarise the 2200 commits, since the last release, into a readable announcement. Also, we need to consider other (non-code) ways in which people have helped us. e.g. Bug reports, Helping people on IRC, etc.
Once the Notes have been completed, they need to be transformed slightly for the different media and audiences.
The management repo contains templates. These are just suggestions.
It’s probably easiest to start with the github template, writing in Markdown, then simplifying it where necessary.
This is one of the slowest parts of creating a release, but also one of the most important. The users want to know of all the new features and the contributors want to see their name in lights.
This needs to be done for all the NeoMutt repos, but clearly the majority of contributions will be in the neomutt repo.
Getting the list of contributors is simple.
Upstream committers can be excluded unless they’ve directly contributed to NeoMutt.
See the mailmap notes for more detail.
git shortlog --summary --email neomutt-20180716..
Next, get a list of all the commits
git log --graph --format="%h %s" neomutt-20180716..
We need to get the right level of detail, which means culling most of the information. Start by looking for branches with similar commits, e.g.
These can quickly be summarised in a single line. Next, look for significant events:
Finally start grouping similar commits, looking for patterns that could be summarised.
Do NOT let this take too long.
Most people won’t read far into the Release Notes.
Notes This first section is a brief overview of the Release. It should include any important notes that the user should be aware of.
Thanks Here, we divide up the users into new and regular. Both lists should be randomised and @flatcap should be omitted.
To find out if a user has contributed before, it can be helpful to grep the website _posts directory.
These are the important bullet-points to sell:
Other significant changes:
These may be of interest to developers:
