Use Conventional Commits and semantic-release

[kodebach]

@markus2330 @mpranj @robaerd

Did any of you consider using "Conventional Commits" and the semantic-release system? It would semi-automate the creation of the release notes and reduce merge conflicts (because the _preparation_next_release.md isn't needed anymore).

https://www.conventionalcommits.org/en/v1.0.0/
https://semantic-release.gitbook.io/semantic-release/

The commit format could be checked with a GitHub action, similar to what we do for the release notes. The check should, however, be separate so that we can develop code without using the convention for every commit. Then at the end of a PR we squash everything down into one (or a few) commit that conform to the convention. Always using a squash merge (AFAIK this can be enforced in the GitHub settings) would also be an option. But then you have to remember to write a correct description when merging, because the commit message for a squash merge cannot be checked AFAIK.

There are some pre-built actions that do checks similar to "Conventional Commits" for PRs (e.g. https://github.com/amannn/action-semantic-pull-request). We could also build something custom. Then we could enforce that the PR description follows "Conventional Commits". I think the PR description is the default suggested by GitHub when using a squash merge.

---

Note: This is only a vague idea, but I think something like this would be much better than our current _preparation_next_release.md. If we do anything like this, it should only be after 1.0. Then PRs should become smaller and which is much more manageable for "Conventional Commits".

[markus2330]

I tried to do something like this (long time ago) but it is too difficult and the result is not as wanted. The wanted granularity of (merge) commits and release notes simply does not match.

Furthermore, it would be a huge practical problem as the commit message of the merge commits are written by the merger and we want the release notes written by the authors.

The constant merge conflicts are a problem of GitHub, not from Git. If you merge locally you see that there are no merge conflicts due the union merging. (doc/news/.gitattributes)

Would be interesting if others (like GitLab) are handling this better. Recently GitHub made problems that I could not add someone and needed a reverification that I am employed at an university. So long-term we probably need to move away from GitHub anyway.

[markus2330]

The "problem" could be the "abgaben" repo, which is private and the whole ElektraInitiative group has access to it.

[kodebach]

I randomly found this post today: https://github.community/t/what-do-these-changes-mean-for-me-if-i-m-on-a-legacy-plan/18547

Could it be that the Elektra organisation is still on one of those legacy plans and that's why there were problems adding people without the education status?

[markus2330]

I don't know on which plan we are. As we renewed quite recently we are probably not on legacy plans?

[kodebach]

These are the steps for changing the subscription of an organization, I assume somewhere on that settings page, it should list the current plan.

As we renewed quite recently we are probably not on legacy plans?

I'm not sure about that. The new plans are all either free or per-user pricing. Maybe confirming your university status, just extended the legacy plan. It doesn't really matter either way right now, I just wanted to mention that it since I saw the post.

[markus2330]

The current plan is: "GitHub Team
Advanced collaboration and support for organizations"

[kodebach]

I thought about a few alternatives, but I think the best solution would be this:

• Every PR #XXX must add a plain-text file doc/news/next_release/#XXX.
• For each change the PR makes (e.g. bugfix, new feature, doc change, etc.) there has to be a description in the file.
• Change descriptions are separated by --- (alone in a line).
• Every change description on its own follows the conventional commit specification.
• We also require an Author footer for each description (like the Reviewed-by here)
• For things like "Highlights" we could also use footers.
• To generate release notes we basically do the same as semantic-release, but instead of using commit messages we use our doc/news/next_release/#XXX files.

This way we still get the granularity we want (n changes per PR) and the difficulty is basically the same as the current system. But crucially, since we use one file per PR there shouldn't be any merge conflicts (not locally and not on GitHub). If a PR is an update to a previous one, we could also allow adding e.g. doc/news/next_release/#XXX.update.#YYY to indicate #XXX doesn't have its own file but instead update the file of #YYY.

---

As a reminder, these are just ideas and I would not implement them before 1.0 (unless somebody has the time to test all this).

[markus2330]

Having several files is basically a workaround for the non-working union merge driver. Let us wait for the GitHub answer and if we switch we would see if it is also a problem in GitLab.

As a reminder, these are just ideas and I would not implement them before 1.0 (unless somebody has the time to test all this).

I don't see this related to any milestone.

[kodebach]

I don't see this related to any milestone.

It depends on the solution we go with. Before 1.0 there will be some big PRs that will be hard to split neatly into conventional commit messages. After 1.0 everything should be stable and changes should be a lot more separate from each other.