Support auto gen of the changelog.md

[ryaneberly]

gradlew gitChangelogTask to rebuild the CHANGELOG.MD from the tags on github.

it will be more accurate next release, since we are using github releases (and maven) moving forward.

[TheRealAgentK]

Can we customise this or have chunks of text in there that allows us to add additional info?

I've just added an "overview blurb" on top of the file and it'd be great if we had a way to combine generated issue lists with more manual content.

[ryaneberly]

I agree. I don't' think that is supported with the current one I grabbed.

There's one written in ruby which does: https://github.com/skywinder/github-changelog-generator

I was trying to keep it simple. But it does need to be useful too

[TheRealAgentK]

Just looking into this now. I'll give this Ruby gem a go and see how it goes. It'd be slightly annoying as it won't be nicely integrated into Gradle.

And option might be to just continue to use the existing plugin and add a few lines of "commentary" - non-generated - to README.

[TheRealAgentK]

Ok, this is possible to do.

After installing the package, updating ruby and gem and whateverelse...

It would need to be run with:

github_changelog_generator -u cflint -p CFLint --token <githubtoken> --output CHANGELOGNEW.md --base CHANGELOG.md --no-unreleased --since-tag <previousTag> --header-label

Essentially it'll then just keep everything from CHANGELOG (including manual additions and overview/summaries for a release) and prepend the file with the new information, write it to CHANGELOGNEW. Then, the manual bits get added to CHANGELOGNEW, rename and put in place, commit etc for release.

Still a manual step involved, but I guess as soon as we'd want to have a more humanised overview instead of just a list of issues fixed, that's unavoidable.

I'm happy to do it for the 1.3 release, let me know what you think. @ryaneberly @KamasamaK

[ryaneberly]

@TheRealAgentK
Ideally the changelog gen is just be another step in the (gradle) deploy process.

If github_changelog_generator works well for us, go for it. I like the consistency of something mostly automated.

[TheRealAgentK]

I've got it (somewhat clunky) integrated with Gradle in a feature branch. Because it executes binaries/shell scripts from Gradle, I can't really build/test it for Windows and my OS X solution relies on tools like awk, tail and a proper shell to be there. Not sure what you can do there on the Windows end.

Will bundle it up and push with an initial changelog (containing the "old" manual commentary) in that branch.

The old solution is still there, moved it from "other" into "documentation" group in Gradle, though.

[TheRealAgentK]

This has been (non-destructively) merged into dev - please have a look... Some more commentary in the PR ticket:

https://github.com/cflint/CFLint/pull/512

And this is an example of the new Changelog file (based on dev branch):

https://github.com/cflint/CFLint/blob/dev/CHANGELOG.md

If we think this is too clunky and too hard, easy enough to remove again.

[ryaneberly]

That's pretty high class documentation for a couple of part-timers like us. 👍

[TheRealAgentK]

@ryaneberly did you just take over the changelog from dev and rename/change the links from 1.3.0-RC2 to 1.3.0 for the first section? I think that's caused a bunch of stuff to be missed because of when I ran the changelog in the 382 branch, it wouldn't have had access to certain thing that happened in the meantime in the master and dev branches.

I think the process has to be:

1. Decision to "release" a certain master changeset as x.y.z
2. Be on this changeset with an empty working copy
3. Run changelog script before creating the x.y.z tag
4. Commit the new changelog file
5. Tag with x.y.z.

Currently any deviation from this process will cause inconsistencies. Also - I think tags for releases or betas/rc always should be done on master - I think that's what we've been doing anyway though.

I'm transplanting the 382 changes into master manually now and will re-run the changelog in there.

[TheRealAgentK]

The new changelog generator is now independent of hardcoded paths in the code/gradle file and relies on a not-to-be-committed (and already .gitignored in master/dev) user.properties file in the project root.

Content needs to be:

user.githubChanglogGeneratorBinary=<absolute path to github_changelog_generator binary>
user.githubToken=<your github token>

In my case (Using rbenv to manage multiple Ruby/Gem setups on my Mac) this looks like (redacted my Github token for obvious reasons) :

user.githubChanglogGeneratorBinary=/Users/kai/.rbenv/shims/github_changelog_generator
user.githubToken=<kai's token>

All the code and gradle changes are now in master and dev of the main repo and can be used. Until we've worked out the kinks around Win/Mac/Linux and process, you can just let me know to help with a beta/rc/final release :)

[ryaneberly]

@TheRealAgentK, you up for generating the changelog for 1.4.0?