Maintain a Changelog

[seisman]

In my opinion, a changelog is essential for any software, especially for open-source software like GMT.

I know that GMT once had a changelog file, but it was deleted two years ago due to the lack of maintenance. The old changelog recorded almost every changes chronologically, which is not useful for users to have a quick view of what's new and what's changed in the new release.

A changelog should contain a list of notable changes for each version of a project. The changes should be grouped based on the types of changes, like "new modules", "new features", "fixed bug" and "incompatible changes". Although we already have a GMT_Changes.rst in the documentation, it seems only updated for major and minor releases, not for bug-fix releases, and I don't find any information of the changes between the upcoming 6.0.0 and the 5.4 release.

I suggest we should keep a changelog in the top directory (maybe a symbol link to GMT_Changes.rst is enough), and modify the changelog file in PRs with notable changes.

[leouieda]

I agree with @seisman. A changelog would be very useful. What I have been doing on other projects is using the git history to make a changelog before each release. For this to work, it really helps if PRs are self-contained (meaning that we avoid merging broken PRs and fixing them in later PRs) and writing extensive commit messages when merging the PRs. It's not too hard to then generate a basic changelog from the git log and manually separate into categories. It would also help if the PR/commit message clearly states if the change breaks any compatibility, fixes a bug, etc.

[holishing]

Is it possible to maintain or just make a note about changes in master branch in github wiki page ?

• about permission settings: maybe only maintainer can edit that wiki, or some users interested in the project can also help to improve related details or more.

another possible benefit is content changes in change log will be separated from commit log, frequently change the change log will not let commit logs be more complicated.

[seisman]

@leouieda and @holishing, I have a different opinion about how to maintain a changelog file.

If someone wants to make some changes (new features or bug-fixes), he should open a PR and also add the changes to CHANGELOG in the same PR. Thus when the PR is merged, the CHANGELOG is also updated, and the PR is self-consistent.

We can also add it to the PR checklist to remind contributors to add the changes to CHANGELOG.

[leouieda]

@seisman I tried doing just that for many years. The main problem is that every single PR would create a merge conflict that needs to be solved manually. It's much easier now that Github allows resolving conflicts online but it's still a hassle and possibly a barrier for new developers.

[seisman]

Based on my experience of releasing GMT 6.0.0 and 6.1.0, the most time-consuming tasks in the long release checklist are:

1. testing tarballs, macOS bundle and Windows installers in clean environments (~one hour or more)
2. updating the changelog (~30 minutes?)

For the first task, we already have the gmt-release-testbot to automatically install macOS bundle and Windows installers in clean VMs and run some tests (although @PaulWessel and @joa-quim still ran the installers using their own machines). The testbot can/shoudl be improved to be able to build source tarballs in some Linux distros, too.

The 2nd task is manually done by @PaulWessel. It looks a tedious work to me (@PaulWessel may agree with it or not).

The PyGMT project is using the release drafter github action (setup by @weiji14) to automatically generate the changelog. It's similar to what @leouieda mentioned above but is more automatic:

What I have been doing on other projects is using the git history to make a changelog before each release. For this to work, it really helps if PRs are self-contained (meaning that we avoid merging broken PRs and fixing them in later PRs) and writing extensive commit messages when merging the PRs. It's not too hard to then generate a basic changelog from the git log and manually separate into categories. It would also help if the PR/commit message clearly states if the change breaks any compatibility, fixes a bug, etc.

The release drafter creates a draft release (only visible to developers). When a PR is correctly labelled and merged into master (or a specific branch), it will create an new entry in the draft release page using the title of the PR. See the PyGMT changelog for what the automatically generated changelog looks like.

It seems very useful and can save a lot of time for a release. As mentioned above, for this to work, the core developers must change the way they write PR title (PR title is listed in the changelog) and description, and also label a PR correctly (e.g., "feature", "bug", "maintenance") before merging a PR. A well-written PR title and description also make it easy for us and others to recall why we made the changes years ago.

[PaulWessel]

Yes, ChangeLog is painful since there is nothing automatic about it. If we had discipline to add string to flag a new feature or new program then maybe we could strip those out, since listing all the bug fixes is probably not worth it.

[leouieda]

since listing all the bug fixes is probably not worth it.

If it’s automatic, then I don’t see the harm in keeping them.

Release drafter does seem to work pretty well. It not much work to use a descriptive PR title and add a label when compared to trying to curate a change log from git history manually.