Open santisoler opened 1 year ago
This is an idea. I would like to hear what other people think and if it worth the effort.
On a side note, there are a few guidelines in keepachangelog.com that I wouldn't implement. For example, I don't like to edit the changelog on every new PR, I prefer to produce it before the release. With the Squash&Merge strategy the process is really easy, and I don't think we should be thinking about the changelog on every PR. It's nice to have the changelog building up for the dev version of the docs, but I think it's not something that worth the effort.
Hi @santisoler I think it would be fine to have the CHANGELOG.md
file. I've been wanting to migrate the changelogs to Markdown for a while to reduce a step in the release process. We could include it in doc/changes.rst
the same way we do with doc/citing.rst
and CITATION.md
.
Description:
This week I came across with https://keepachangelog.com/, a nice project that sets guidelines for writing changelogs in a simple way. I was happy to see that we are already following most of their guidelines (dividing in categories, linking the items to PRs, adding the release date to each version, latest goes first, etc).
Although there are some neat ideas that we are not strictly following. I think the main one is keeping the changelog in a Markdown file called
CHANGELOG.md
in the root of the repository. Instead, we keep in achanges.rst
file inside thedoc
folder. I think the name is not the best one (changelog > changes), and keeping it hidden in thedoc
folder makes it harder to discover it.Moreover, in our Release checklist we instruct maintainers to create a Markdown version of the changelog to be pasted in the GitHub Release notes. So we are already generating the changelog in Markdown at some point in the release process.
So, my proposal would be to:
doc/changes.rst
files in our repos to aCHANGELOG.md
file in the root of the repositories. Sphinx will have to load that file to create the changelog in the website.CHANGELOG.md
(in Markdown)Apply to:
Further instructions:
Related to fatiando/community#105
We want your help!
We know that maintenance tasks are very demanding, so we don't expect a single person to tackle this issue by themselves. Any help is very welcomed, so please comment below that you want to take care of the changes on any repository and we will assign it to you.