NEO.MJS RFC: Introduce mandatory format for commit messages

[ThorstenSuckow]

NEO.MJS RFC: Project specific commit format

• Version: 1.0
• Date: 24.06.2022
• Author: Thorsten Suckow-Homberg [email protected]
• Status: Draft
• Versions affected: V4.0.51

Introduction

This RFC proposes to introduce a commit message format into the project. A global format for commit messages helps in understanding commit history and describing changes more explicitly.

The current situation allows for any type of text without further checking on the format and syntactical validity of the message itself.

Proposal

The Conventional Commits specification is a widely known and accepted specification for structuring commit messages, effectively allowing to tag commits with a type, a scope and the commit's intend:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

It dovetails with SemVer which the project already uses for identifying release versions of the software.

It also provides the benefits in helping with automatically generating CHANGELOGs

Changes that affect the current specification

None, since currently no specifications exist. However, on top of the current set of the tools used, a pre-commit hook would be recommended to check for the validity of the commit message:

https://github.com/conventional-changelog/commitlint

This can be easily integrated into the project using npm packages.

[ThorstenSuckow]

Feel free to create a ticket out of the issue and assign it back to me for a PR.

[davhm]

Big strong fat +1 -- I've annoyed @tobiu with this before because I fully agree with the value it provides

[tobiu]

well, i am open to the change. might slow me down a little bit while getting adjusted at first^^

in case we create a required format, i would also make a reference to a related ticket mandatory.

[ThorstenSuckow]

I'd probably leave the "refs" out of the mandatory requirements for a commit message, since changes tagged with "style" or general housekeeping would clutter the issuetracker with too many unnecessary tickets which would have to be opened before a commit can be executed, e.g. for a code format change I'd think this would rather be a tedious task.