Adopt Conventional Commits and Semantic Release Bot

[jGleitz]

Consider this scenario:

Emma uses atrium to test her software. She discovers a bug which blocks her. She files an issue and submits a PR. Because atrium is very well maintained, the PR gets merged very fast. Emma is happy, but she still has to work around the bug until a new release of atrium is published. Even if atrium was publishing development releases, Emma would need to activate the dev repository and then don’t forget to switch back to the release repository later.

Emma’s problem could be solved by publishing a new version of atrium as soon as a feature has been merged. This process can be automated by using conventional commits and semantic release. This would give us further goodies, like an automated message on the issue and PR which version number contains the fix.

Some pros and cons I see:

1. Contributors need to use conventional commits. This can mostly be mitigated by squashing their commits and setting the PR title.
2. Users might be annoyed that their automatic dependency updater produces a lot of noise when we release often. Users could mitigate this by setting their automation up to either merge minor releases automatically or to not post them about updates of the same dependency too often.

[robstoll]

I like your basic idea. Not sure if about conventional commits and the semantic-release bot though. As you wrote it means some extra effort by me as I need to go and fix the commit descriptions of contributors (I doubt we get contributors to actually follow conventional commits).

I don't know semantic-release bot maybe you can answer a few questions:

1. does it support the idea of alpha, beta, RC releases? I would still like to have those especially when I introduce breaking changes as I might re-break them within the alpha cycle
2. What is required by the bot to release? or in other words, what do I need to give away to the bot in order that it can perform the release. (I know I could read it up but I a don't have time and maybe you can summarise it here in case you have time)
3. well.. that's already it for now :cat:

[jGleitz]

some extra effort by me as I need to go and fix the commit descriptions of contributors

Not necessarily. You could also edit the PR title and squash. Both can easily be done directly from the GitHub user interface. The bot can also add a check to PRs. This way, contributors would directly get feedback that they don’t follow the conventions. I guess that most contributors would see it and fix it themselves (that’s what I did, at least).

does it support the idea of alpha, beta, RC releases?

It does, here is some documentation about it: Publishing Pre-Releases. The workflow is based on creating branches for the pre-releases. I guess that makes sense since it allows you to still add features to the stable release while already working on the (breaking) pre-release.

What is required by the bot to release?

Not much, really. You have to execute the bot in your CI environment, but there are no restrictions on which CI we use. The bot would create a GitHub release and we could execute our own deploy logic in reaction to the GitHub release. For string-notation, I set up a GitHub workflow that reacts to GitHub releases and publishes to Maven Central. I had a good experience with it.

The bot can also commit a changed gradle.properties file to automatically update the version number.

In summary, the bot allows us to automate the whole process, but I don’t think it puts any real restrictions on our workflow.

I know I could read it up but I a don't have time

That’s fair.

[robstoll]

The bot can also add a check to PRs

That sounds good

The only thing open to me is that I want to have control over what changes are released, i.e. what makes it into master. Currently all contributors can push to master which is OK as it's not released immediately. Thus we would need to switch the repository to an organisation first to have this more fine grained control.

[jGleitz]

Thus we would need to switch the repository to an organisation first to have this more fine grained control.

I like the idea of having an organisation for atrium.

However, you could also just turn on branch protection, but not tick the box that makes it apply to administrators. That way, only administrators (effectively: you) can push to master.

I actually assumed that this was already the case :D

[robstoll]

I see that I misunderstood the code-owner part, I activated the restriction now. This way we are not blocked for this issue, we can introduce an organisation later on. I see benefits there as well, I am just not yet sure if I want to move things to the organisation tutteli, so that I have everything at one place (e.g. also kbox) or if I move atrium and atrium-roadmap to the organisation atriumlib

[robstoll]

Another question. How does it deal with breaking changes in 0.x.0 versions. Does it increase the major version? Not that it's a problem if not, then I would simply not add the corresponding keywords to the commit message.

[jGleitz]

0.x versions are not supported:

Can I set the initial release version of my package to 0.0.1?

This is not supported by semantic-release as it's not considered a good practice, mostly because Semantic Versioning rules applies differently to major version zero.

If your project is under heavy development, with frequent breaking changes, and is not production ready yet we recommend publishing pre-releases.

See “Introduction to SemVer” - Irina Gebauer for more details on Semantic Versioning and the recommendation to start at version 1.0.0.

In short, the best practice seems to be not to use 0.x version, but instead, use postfixes like -beta.

[robstoll]

@jGleitz As preparation for this. In order to support continuous deployment we need to automate a few things. Could you create a shell script which (using sed or something similar) carries out the manual steps described at the end of build.gradle for master

Moreover, prepare a github workflow which:

• triggers on branch creation where it should only run if:
  • branch name matches releases/.*
  • if I created the branch (I think something along the line of github.event.sender.login = robstoll)
• calls the script you created
• publishes to bintray
• publishes to maven central
• create and published gh-pages for major and minor versions
• creates and pushes a corresponding tag
• merges back to master

I don't know what trigger the semantic bot supports, but I guess based on a created tag should be possible. It could then create the github-release. Needless to say, this workflow will already be a big help even if we are not going to use semantic release bot

[robstoll]

won't be tackled