Should we use standard "semantic versioning" (13.x.y) for MATSim libs?

[billyc]

Many projects have adopted a specific versioning scheme for public releases, using the "major.minor.bugfix" system to categorize releases as having breaking changes, feature updates, or bugfixes only. I think this has been discussed before but I wanted to bump the idea once again.

What's new is that there is now automated tooling that can automatically bump the version number based on standard "conventional commit" git commit messages and auto-generate a changelog based on those commit messages, too. I've been using this for the SimWrapper data viz tool for a few months now; you can see the changelog here.

It nicely separates bugfixes from feature updates, and provides direct links to the Github commits that implement each change. That's a lot of automation for free -- all you have to do is make sure the first line of your commit message follows the guidelines, and voila.

MATSim has special needs so I don't know if this type of versioning is appropriate, but the changelog functionality seems like it would be really useful.

Note the "standard-version" tool I linked to is a javascript tool but it works with any source code, regardless of language; there exists a maven plugin. Perhaps there's a native Java tool that does the same thing; might be worth looking into...

[1] Standard-version tool: https://www.npmjs.com/package/standard-version
[2] Conventional commit specification: https://www.conventionalcommits.org/en/v1.0.0

[Janekdererste]

I like the changelog. I have no oppinion on the numbering scheme though.

[sebhoerl]

In general, I'd be happy with anything that gives us a nice changelog :)
Are there automated checks for the format of the commit messages?
Regarding versioning, I don't have a strong opinion, since we have the PR builds now.

[billyc]

I think we could add git check-in hooks to enforce commit message format, if we really want to forbid non-compliant checkins. We're not currently enforcing any sort of discipline on commit message format now, are we?

Maybe the next step is for me to spin up a little demo so we can see how it all functions. Who is in charge of pushing out the MATSim builds right now? I can work with them.

[michalmac]

I have been using commit conventional commits for a few years now. It's nice, but requires a high self-discipline when it comes to creating commits, in particular:

• how to enforce everyone uses chore, feat, fix and other prefixes properly?
• if a PR consists of many trial and error commits - they should be squashed, otherwise the changelog would be a mess

We had some discussions in the past about changelogs, linear history etc. (@sebhoerl maybe you can find it somewhere on github or confluence/jira)?

I am not aware of any good mvn plugins for conventional commit linting that work flawlessly (at least I couldn't fine one last time I tried), so we would likely need to use js. This also means that running mvn verify locally does not guarantee that build (on GH Actions) will succeed.

If we decide to use conventional commits, we should make some decisions on how to make our git logs cleaner. Otherwise we would make our builds/CI more complex but without gaining a lot.

[billyc]

@michalmac -- yes to everything you just said :-)

The commits require discipline, so what I find works best for me is to be loose with my commit logs on a branch, including the trial/error commits that always happen; and then when the squash commit comes which wraps everything up, I try to write a nice compliant commit with helpful explanation text below. The squash commits always list the full commit history in the details anyway.

PR squash commits really do make this work a lot better. But I think this might be an emergent recommendation: squash commits make the git history more readable & usable anyway! Especially if a PR consists of many trial/error commits -- that is just noise that makes git history difficult to understand.

I'm still going to experiment with this a bit and get back to the group, acknowledging that it is not a perfect solution.

[michalmac]

@billyc I agree this is a good direction to try out and I also hope it may bring some additional co-effects (like cleaner git log).

Who is in charge of pushing out the MATSim builds right now?

AFAIK no one specifically in charge of it, but recently it's been mainly me (GH Actions) and @mrieser (matsim mvn repo). Let me know if I can help. Maybe some re-design in workflows would be worth considering, e.g. triggering builds on new (semantic) tags rather than on PR/release events.