Move changelogs to CHANGELOG.md in the root of repos?

[santisoler]

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 a changes.rst file inside the doc folder. I think the name is not the best one (changelog > changes), and keeping it hidden in the doc 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:

1. Move the doc/changes.rst files in our repos to a CHANGELOG.md file in the root of the repositories. Sphinx will have to load that file to create the changelog in the website.
2. Update the release checklist:
   • Instruct to copy the latest changes to CHANGELOG.md (in Markdown)
   • Update the bash command to create links to PRs (it should create Markdown links instead of rst links)
   • Remove the "generate a Markdown version of the latest changes"

Apply to:

• boule
• harmonica
• pooch
• verde
• ensaio
• choclo
• dependente

Further instructions:

• Start by opening Pull Requests on each repository listed above.
• Optionally, we can open Issues on each repository if further discussion specific to that repository is needed.
• Mention this Issue on every Issue or Pull Request opened on each opened: Related to fatiando/community#105
• Check-off the repository on the list above once the Pull Request is merged.
• Close this issue when all items are checked-off.

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.

[santisoler]

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.

[leouieda]

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.