Add a changelog

[thomasdarimont]

Hello,

could you please add (and maintain) a changelog?

Cheers,
Thomas

[vruusmann]

Do you have any specific recommendations regarding the changelog? Basically, what should be the main "added value" in comparison with the raw Git(Hub) commit log?

I have thought about adding and maintaining a set of Wiki pages with the intention of helping people to migrate from one JPMML-Evaluator version to another. E.g. "upgrading from 1.0.22 to 1.1.0", "upgrading from 1.1.0 to 1.1.1" and so on. But that's a pretty technical point of view. Previously, I have tried to make such announcements in the JPMML mailing list, but I have fallen down a bit with the latest 1.1 development branch.

Do you know some tool that could assist me here? Ideally, it would crunch the raw Git(Hub) commit log between the specified start and end tags, and prompt me for additional comments.

[thomasdarimont]

Hello vruusmann,

It would help others to be able to evaluate the state of the project quicker and make it clear how it evolved over time. Sure you can asses the state of a library by looking at the commit log but it shouldn't be the only source for that kind of information ;-)
A commit log can get quite messy, especially of more people are working on the same project.

Thats how we do it in the Spring Data Team:
https://github.com/spring-projects/spring-data-commons/blob/master/src/main/resources/changelog.txt

For bigger releases we even provide a special "curated" change-log via dedicated wiki-page that lists major new features, improvements or other changes the we want others to be aware of.
https://github.com/spring-projects/spring-data-commons/wiki/Release-Train-Dijkstra

There are some scripts that basically allow you to filter and render your commit log to generate a changelog.
I'd recommend you to start using github issues for your features or improvements that are comming and reference those in the commit message. Then you could filter your commit log afterwards for the pattern like for instance:
#issueID - New feature XXX / Bug Fix YYY
Then it is easy to generate a change-log from that.

Cheers,
Thomas