Create automation for ORT releases (incl. release notes)

[sschuberth]

Currently, there are not fixed releases for ORT available, but only dynamically built artifacts via JitPack. While this works reasonably well for "early adopters" like SW360 Antenna, it would be nice to have "real" releases with semantic versioning.

While a common option is to publish JVM artifacts to Maven central or JCenter, another option for us is to use GitHub's built-in package registry. Publishing to GitHub can the nicely automated using GitHub actions.

As discussed internally earlier, the trigger for a release should be the push of a(n) (annotated) tag of a special name. Luckily, a ready-made GitHub action exists which seems to do exactly that. We should evaluate that action and eventually take it into use to prepare for automating releases in the near future.

Edit: I'll update the following list with suggestions about release tools from the comments below.

• https://github.com/orhun/git-cliff
• https://github.com/jreleaser/jreleaser
• https://github.com/release-drafter/release-drafter (see e.g. semver4j, graphql-kotlin)
• https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes
• https://github.com/semantic-release/semantic-release

[sschuberth]

Creating an ORT release should involve running ORT on ORT in order to create a proper disclosure document, e.g. a NOTICE file, to be bundled with the distribution / Fat JAR for the CLI.

[gongzhao1]

Hi, Is there an official image available in Docker Hub?

[sschuberth]

No, not yet, see https://github.com/oss-review-toolkit/ort/issues/2441. You currently have to build the image yourself.

[sschuberth]

FYI, I recently came across https://github.com/orhun/git-cliff to generate changelog files / release notes from the Git history, which might be interesting for us in this context.

[sschuberth]

Maybe also https://github.com/jreleaser/jreleaser could become useful here.

[aalmiray]

Hi there, I'm the author of JReleaser. The tool can certainly help you craft a changelog based on just commit information. If you're looking for an option to generate the changelog based on GH Issues/PRs then I'd recommend https://github.com/release-drafter/release-drafter

Of course JReleaser works both in local and CI environments.

One more thing, if you're interested in posting ready made binaries (such as CLI based tools) then JReleaser can also help you

• posting those binaries to a GitHub release page
• creating platform packagers for those binaries with Homebrew, Scoop, others.

[sschuberth]

Probably also relevant for us is GitHub's new feature to automatically generate release notes for GitHub releases.

[sschuberth]

Publishing to the new Adoptium Marketplace could also be an option.

[mawl]

https://github.com/semantic-release/semantic-release <= a fine tool we're using.

Integrates with github actions as well: https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/ci-configurations/github-actions.md

[sschuberth]

Idea from @mnonnenmacher at the ORT Community Day: Attach release notes to annotate Git tags to be independent of GitHub.

[sschuberth]

After reading through @pombredanne's https://www.nexb.com/software-versioning/, I wonder whether we could use a mix of CalVer and ideas from SemVer for ORT. The version number "prefix" would be CalVer (for sorting), plus a "suffix" that contains the number of breaking changes, new features, and bugfixes, respectively. The latter numbers could be calculated from our Conventional Commits easily, and in contrast to "pure" SemVer these numbers also give you a clue about how much (not only that) something has changed.

So, for example an initial ORT release from today would have version 2023.7.19+0.0.0 as relative to the previous release (there is none) no changes can be computed. The next release on the last day of next month with 3 breaking changes, 1 new feature, and 5 bug fixes would have version number 2023.8.31+3.1.5. When omitting leading 0 in the date, the whole string is SemVer compliant, and using + instead of - nicely resembles that the following "build metadata" describes what has been added.

[maxhbr]

this might align better with expectations coming from semver if you reverse the order: 3.1.5+2023.8.31. Should still have the same properties.

[sschuberth]

3.1.5+2023.8.31. Should still have the same properties.

That breaks (string) sorting (by date).

Edit: But I just realized omitting leading 0s does, too 😭

[maxhbr]

if the leading version is just increased and every increased version is released at a later date, the sorting should still be the same. (If not just string sorting, but semantically sorting the parts)

[sschuberth]

if the leading version is just increased

The idea was not to monotonically increase the numbers, but to be relative to the previous release.

[maxhbr]

oh, sorry, I missed the relative.

[sschuberth]

As discussed in today's community meeting, we'll like stick to plain SemVer after all, mostly for for simplicity as remembering the date as part of a version (if you want to upgrade) is hard.

[sschuberth]

This is now done (using https://github.com/jmongard/Git.SemVersioning.Gradle).