Tracking CHANGES

[fmigneault]

Sorry, I didn't think about that before bird-house/contributions-guideline (#156) was merged... I would like to amend something.

What came up and made it very obvious during PRs #152, #154, and probably more to come... is that it is not easy to know what changed between versions. There are effectively no easy way to retrieve full changelogs. With upcoming releases by tagged versions and different forks across organizations, these will become ever increasingly important.

Also, there is no specific guidelines about how changelogs should be tracked, so it is very free-for-all in the commits. I know that @tlvu does very detailed descriptions in his PRs, but any other commit/PR contributors doesn't (including myself). I don't think that is the usual (natural?) way for most developers also, and I find the process of opening individual commits to read descriptions very time wasting/frustrating when I want to find when a change was introduced.

For this reason, I would like to propose to have a standard CHANGES file, as most repos do, and have a proper listing of versions and relevant changes each time. The guideline would also add a requirement to list whatever was changed by each PR, making the info still easy to retrieve within individual merge commits.

The biggest advantages would be:

1. a standard format defined in CHANGES, normalizing how everyone reports them
2. a common place where to look for them, making it easy to retrieve what happened between each version by looking through a single file.
3. easy auto doc in the ReadTheDocs, allowing to also expose the CHANGES in the published/official documentation references
4. possibility to add bumpversion and other useful tools if the need arises

Thanks for feedback and discussions. Whomever it concerns: @huard @tlvu @dbyrns @MatProv
(tag any others as needed)

[tlvu]

Just for the record, almost every PR merged in this repo gets a tag since it is autodeployed so we need some kind of identifier to describe the deployment state.

A few exceptions are PR that only update docs or comments. These PR do not get a tag when they merged.

So a sort of change tracking is the release page https://github.com/bird-house/birdhouse-deploy/releases.

That worked quite well so far when the PR branch is descriptive and detailed PR description is copy/paste into the merge description because then the same content shows up on that page if you expand the 3-dots next to the tag.

But yes I am all for a more format change tracking if we can avoid depending on github release page and if it do not add too much more overhead.

[fmigneault]

We could use the script that does this deployment to automatically run the bumpversion beforehand. That will not introduce extra overhead when merging PRs. @tlvu can you pinpoint where this deploy/tag operation occurs?

The initial CHANGES should be populated from the descriptions provided via those releases notes.

Any future updates would be placed in an unreleased section in CHANGES, which gets bumped to whichever tag is selected once deployed. In case of doc changes, they would be under the same version and the new deploy since no tag occurs.

[fmigneault]

@tlvu I've made a rough draft from extracted tag/releases messages: https://github.com/bird-house/birdhouse-deploy/pull/161

If you can tell me where/how the tag releasing occurs, I can work on a bumpversion call to update that file on each new PR.

[tlvu]

If you can tell me where/how the tag releasing occurs, I can work on a bumpversion call to update that file on each new PR.

I will have to deceive you for this one. I just git tag manually and git push --tags. There are no other files containing the tag so no need to update any files when tagging. Everything is still simple and lightweight in this repo, for now.

The tagging policy numbering is here https://github.com/bird-house/birdhouse-deploy/blob/master/birdhouse/README.rst#tagging-policy

[tlvu]

So if I understand correctly, dev will prepare the changelog ahead of time (as they work on the PR) and will use the new changelog to populate the PR description? I like that idea.

Since you're into a lot of github workflow automation, is there a way to auto-populate the PR description into the merge commit description? Here's why I like to do this:

• It preserves the "latest" update of the PR description, which might not all be captured in the changelog while PR discussion goes on.

• It makes the repo itself independent from the hosting (Github) because the summary of all the discussions in the PR is then in the merge commit description which is in the repo. Basically someone clone the repo, has all the relevant info about each PR. No need to load up a browser to get additional info about a PR and no vendor locked-in into the hosting to get additional info about the PR.

[fmigneault]

I don't think there is an easy way to automate the PR from the changelog. There would need to be a script that filters/extract only the most recent block of changes, and then request via github API to push that content as a new PR with the referenced feature branch.

This could be achieved with a Github Action, but it is probably not the most obvious workflow. I can imagine some confusion from users when opening a new PR, that would then have its contents overridden by the changelog.

Usually, I tend to properly define the changes/fixes in the CHANGES file, and practically copy-paste them in the PR description. It's also easier to flag the PR as "requesting changes" until this CHANGES is correctly applied, instead of the merge comment that is easy to forget.

[fmigneault]

If there is no other file to update for now, that is fine. The procedure would change to bump2version call followed by the same git push --tags.

We could actually add the latest version references/badges in the README similar to what Magpie does: https://github.com/Ouranosinc/Magpie/blob/master/README.rst

That would already be 2 files to apply updates (README and CHANGES).

[tlvu]

I can imagine some confusion from users when opening a new PR, that would then have its contents overridden by the changelog

Absolutely, I did not meant to automate from changelog to PR description. Manual copy/paste here is fine because the PR template is different than the changelog anyways.

I meant automate from PR description into the merge commit description (this is the step were most user forget).

We could actually add the latest version references/badges in the README similar to what Magpie does: https://github.com/Ouranosinc/Magpie/blob/master/README.rst

That would already be 2 files to apply updates (README and CHANGES).

I guess yes. This repo will only have the "releases" badges.

[fmigneault]

Oh I see! I think that could be possible with a Github Action executed on close trigger when PR is merged, but probably only with an update of the commit text following the merge (similar to a git commit --amend followed by git push -f). I'm not sure if editing that will cause issues though since bots are looking at master-merge to launch tests with those specific commits.

[tlvu]

probably only with an update of the commit text following the merge (similar to a git commit --amend followed by git push -f).

Oh that would be bad. It would be preferable for user to see the "enhanced comment" before clicking "Merge". And a git push -f is often a bad idea, except when a personal branch.