Merge commits and release notes


#1

When I created a release I had to go through all pull requests and copy the release notes from the description. Then I was wondering if there is a better way.

In another project, we use git log production/master.. --merges for a quick overview of what we are about to deploy. Doing that with the OFN codebase gives me a rough idea as well, but it would be even better to see the release notes in there. Currently we see something like this:

commit 8a3f621b42dfa1248d6b647bcf53befe83790c28
Merge: 7cac4637f dc5302ca0
Author: Pau Pérez Fabregat <saulopefa@gmail.com>
Date:   Thu Oct 25 18:20:42 2018 +0200

    Merge pull request #2893 from luisramos0/deleted_products_break_inventory
    
    Fix bug in inventory management page

commit 7cac4637fe566c32e17402ed3cf0b5ad7a19443d
Merge: acb8ec772 c9784a5ed
Author: Pau Pérez Fabregat <saulopefa@gmail.com>
Date:   Thu Oct 25 18:18:53 2018 +0200

    Merge pull request #2916 from luisramos0/date-transl-fix
    
    Add Portuguese and German to list of momentJS locales

commit acb8ec772ec08c5c1b7239bd70707017dda1c432
Merge: 3cab3d179 cd5c23993
Author: Maikel <maikel@email.org.au>
Date:   Thu Oct 25 14:48:51 2018 +1100

    Merge pull request #2922 from mkllnk/update-rubocop-todo
    
    Update rubocop todo list

Imagine we would copy the release notes in the merge commit message when we merge. Git could give us all the release notes with one command. It could look like this:

> git log v1.21.0.. --merges
commit 8a3f621b42dfa1248d6b647bcf53befe83790c28
Merge: 7cac4637f dc5302ca0
Author: Pau Pérez Fabregat <saulopefa@gmail.com>
Date:   Thu Oct 25 18:20:42 2018 +0200

    Merge pull request #2893 from luisramos0/deleted_products_break_inventory
    
    Fix bug in inventory management page

    Fixed: Fix broken inventory page. When a producer deletes a permission for a hub to add producer's products to the hub's inventory, the hub's inventory items are now being correctly updated with a revoked stamp that will not break the inventory page anymore.

commit 7cac4637fe566c32e17402ed3cf0b5ad7a19443d
Merge: acb8ec772 c9784a5ed
Author: Pau Pérez Fabregat <saulopefa@gmail.com>
Date:   Thu Oct 25 18:18:53 2018 +0200

    Merge pull request #2916 from luisramos0/date-transl-fix
    
    Add Portuguese and German to list of momentJS locales

    Fixed: Fixed Portuguese and German translation problem in the shopfront order cycle closure time.

commit acb8ec772ec08c5c1b7239bd70707017dda1c432
Merge: 3cab3d179 cd5c23993
Author: Maikel <maikel@email.org.au>
Date:   Thu Oct 25 14:48:51 2018 +1100

    Merge pull request #2922 from mkllnk/update-rubocop-todo
    
    Update rubocop todo list

    Ignore for release notes.

If this goes well, we could even automated the generation of the commit message. What do you think about this practice? We could also agree on putting the release not line in the title of the pull request. The title is added to the commit message by Github and then we don’t need to copy and paste anything.

@luisramos0 @Matt-Yorkley @sauloperez


#2

yeah, I’ve also tried to make it easier. But ended up doing it manually as it is always good to curate the release notes as you copy paste them to the release notes page.
I tried to use https://github.com/github-tools/github-release-notes without success.

I think we could make the title of the PR the release notes, but that will require some discipline…


#3

I have kind of the same feeling. I also think that it’s a too manual process but the release manager always ends up rephrasing or fixing the notes.

I’ve also checked tools to automate this process and none seemed to adress this issue. They end up somehow looking as notes to be read by robots.

At my previous company we had a script to fetch the notes from PR titles which made us eventually abandon release notes completely. In that context they were not as important as in OFN.

Regarding the idea you suggest @maikel, I wonder if a proper release note will fit in a title. Doesn’t GH break it when it is too long? Agree with you that the part needing automation is the retrieval of the notes from each PR.


#4

I agree that it still needs a human to review the release notes and possibly rephrase them. The retrieval is the thing I would like to automate. So if we can get the release notes into the merge commit somehow, it would be really easy.


#5

Now that I’m at it, I gave a shot at using Github’s API. Seems something rather easy. Here’s what I managed to do (I use the awesome jq)

Retrieve last release creation date

curl https://api.github.com/repos/openfoodfoundation/openfoodnetwork/releases/latest | jq '.published_at'
"2018-10-09T15:31:44Z"

Get a PR’s release notes

curl https://api.github.com/repos/openfoodfoundation/openfoodnetwork/pulls | jq '.[4]|.body' | sed 's/.*#### Release notes\(.*\)####.*/\1/'
\r\n\r\nProduct Import is now available for enterprise users.\r\n\r\nChangelog Category: Added \r\n\r\n

These combined could really speed up this notes-fetching process.


#6

I know it’s a bit messy but I ended up writing the release description running the following commands. I allowed me to be faster and commit fewer mistakes.

So, in addition to those commands described above and with the help of some Vim voodoo I ran

echo '2876: ' >> release_notes.md && curl https://api.github.com/repos/openfoodfoundation/openfoodnetwork/pulls/2876 | jq '.body' | sed 's/.*\(#### Release notes.*\)####.*/\1/' >> release_notes.md && echo '\n' >> release_notes.md
...

with each of the PRs that were to be included in the release (by using search filters in Github). This downloaded the notes, which I further edited manually before pasting them in the release draft.

I hope this helps a bit at automating this process.