Skip to content

Update commit and MR templates

I would like to suggest some changes to our commit and MR workflows as I think there is room for further improvement here. The end result should make things easier for the developers (by having clearer guidelines, more structure, and reducing some redundant operations), while making the resulting changelog entries nicer and more structured.

Commit template

Currently:

  • A commit can only be linked to a single issue, even though its MR might close/fix multiple issues
  • The changelog entries are very coarse-grained, making it difficult for people to discern what is relevant/interesting for them. For example, we essentially only have feature, bug fix and maintenance.

To solve the first issue, I would propose to link each changelog entry to the corresponding MR. This is already supported out of the box by the current changelog generation we are doing, so from an implementation standpoint, this is easy. Moreover, it removes the need for developers to explicitly add the issue: ... trailer to their commits (which is essentially unnecessary work).

To solve the second issue, I would propose we just copy what GitLab does: https://docs.gitlab.com/user/project/changelogs/#add-a-trailer-to-a-git-commit

This means we would have the following commit trailers:

  • addition: New feature
  • fix: Bug fix
  • change: Feature change
  • deprecation: New deprecation
  • removal: Feature removal
  • security: Security fix
  • performance: Performance improvement
  • other: Other

This also gives us the opportunity for the developers to read this: https://docs.gitlab.com/development/changelog/#what-warrants-a-changelog-entry as not every change warrants a changelog entry. The benefit is that for the end-users it will be easier to spot what changed and it allows us to be more consistent and structured with our changelog entries.

Note that I slightly changed the naming here in comparison to what GitLab uses so that we can have a 1:1 mapping for the issue type: .. label as well.

MR Template

Currently, we have the following template:

### Summary

<!-- Please describe the merge request here. Optional if the title already provides a complete description. -->

### Additional Required Actions

- Requires manual tests in pre-production: YES/NO
    <!-- If YES, update https://gitlab.cern.ch/cta/CTA/-/wikis/Manual-tests-on-pre-production and link it here -->
- Requires a documentation update: YES/NO
    <!-- If YES, create an issue with type::documentation label and link it here -->

### References

<!-- Please provide a link to all related issues. -->

For the most part this is fine, but I would propose to change this slightly to:

### Description

<!-- Please describe the merge request here. -->

### Checklist

- [ ] Documentation reflects the changes made.
- [ ] Merge Request title is clear, concise and would be suitable as a changelog entry. See [this link](https://docs.gitlab.com/development/changelog/#writing-good-changelog-entries)

<!-- Further required actions can be added here. -->

### References

<!-- Please provide a link to all related issues. -->

If we need tests in pre-production, an ops ticket should be created and linked so we remove that part from the MR description. Note that a description is mandatory now! This is also how it should be. Of course, you can always refer to the issue for further details if necessary, but when someone looks at a merge request, there should at least be a short description (in addition to the title) describing what it does.

Edited by Niels Alexander Buegel