Auto-generate initial CHANGELOG based on existing releases when using contrib-updater

[thomashoneyman]

The CHANGELOG.md files we've added to existing libraries are essentially a blank slate, prepared to help us move forward by adding to them. But it would really be better if instead the CHANGELOG was generated from the existing GitHub releases.

Given just the release tag, date, and markdown contents, we can fill in historic data with this format:

[ {{releaseTag}} ] - {{releaseDate}}

{{releaseContents}}

And then proceed with the more usual "breaking changes, improvements, other changes" format going forward.

[thomashoneyman]

The API documentation for GitHub releases makes it clear we can pick up the name or tag for the release tag, body for the release contents, and published_at for the date.

[JordanMartinez]

I'm a bit confused. Weren't we going to keep track of changes made via a CHANGELOG.md file and then copy over the relevant parts when making a release? It sounds like this would reverse that (e.g. make a release and then GH will copy that content over into the changelog file).

[thomashoneyman]

I'm sorry, I wasn't clear. I'm talking about when using contrib-updater to generate the correct files for a repository which is either a) being updated for the first time or b) is joining the organization and doesn't have a CHANGELOG already. It would be nice to generate that initial CHANGELOG with all the information from existing releases (without having to do it manually).

Once a CHANGELOG exists then the workflow you're describing is correct.

[JordanMartinez]

Ah! Ok, that makes more sense.

[thomashoneyman]

This should be used to update the CHANGELOG files (for the 17 libraries in #21 as well as the default for new repositories).

[JordanMartinez]

Just to clarify, the output for one release should look like below, right? I'm using purescript-http-methods @ v4.0.2 as an example:

---

v4.0.2 - 7/31/2018

• Added missing case in fromString for PATCH (@bklaric)

---

Note: I wrapped @bklaric in backticks above so as not to tag the person in this issue. Otherwise, the backticks would not be included.

Questions I have

• Could you confirm that we want a hyperlink back to the original release page? I assume yes.
• Should the hyperlink's text be only the release tag? Or should it include the release date as well?

[thomashoneyman]

Could you confirm that we want a hyperlink back to the original release page? I assume yes.

It's an easy thing to do when producing this from existing releases, so we may as well add it. I don't know what the workflow ought to be for updating those links later, though -- when making a new release you want the changelog to be up-to-date, but because the changelog precedes the release you can't link to it (though I suppose you could pre-emptively do so -- link to the release even though it doesn't yet exist, and then create the release).

Should the hyperlink's text be only the release tag? Or should it include the release date as well?

I think the tag itself is fine.

[JordanMartinez]

The pre-emptive release works as long as you're using a tag.

[thomashoneyman]

Ah, the releases link works (ie. /releases/)? Not just the tags link (/tags/)?

[JordanMartinez]

Meaning, it follows a predictable pattern as long as the release is based on a tag:

https://github.com/purescript-contrib/purescript-http-methods/releases/tag/v4.0.2

[JordanMartinez]

I've created the make-changelog-from-release-notes so we can more easily auto-fill the 17 libraries' changelogs