Commit messages for source control management systems

Expressions for communication

Source control management systems (SCM) like Git or Subversion are standard tools for developers. Plenty tutorials spread around in the world wide web how to interact with this technology. But mostly a simple detail got not that much attention, like it should. It's how to write a proper commit message. In this short Blog we discuss why those messages have importance, not only in enterprise projects.

A typical practice are description about code changes like "update build script" or "fix tests". For other persons it is very difficult to catch what exactly was the purpose for the update or change. After a short time is passing, even the original author could not remind as well his activities. This means persons who need to investigate which revision contain a specific change need more time to detect, when the description of s revision is to general. This fact got more importance for collaborative teams using pull requests. For the one who need to decide if a request is accepted or refused, it's very important to figure quit fast out, which decision it should taken. In the next paragraphs we got introduced a new technique about writing very efficient commit messages, everybody can understand quickly. The following graphic is a short overview about a defined vocabulary for writing efficient commit messages.

.

The concept is quite simple and contains tree sections / lines. The identifier is independent and could be something like a feature ID. This ID is not related to any issue management system. Connecting tools like JIRA or Bugzilla you can use the optional section two with the descriptor. Not all projects connected with issue management systems, for that reason this entry is optional. In section tree you are able to give a more detailed information about the revision, enclosed in brackets. A full detail description you find in the paper on Research Gate. As you can see the usage is very simple and easy to extend or adapt. A small example shows you very fast the concept.

[CM-0500] #CHANGE ’function:pom’

{Change version number of the dependency JUnit from 4 to 5.0.2}

Here we see very special feature id. The intention to change a dependency in the build logic can obviously not related to a implemented feature. This is why general task are defined. Those task have the prefix CM and means configuration management. Here is a list of such task we already detect:

• [CM-000] INIT
• [CM-010] REVIEW
• [CM-020] BRANCH
• [CM-030] MERGE
• [CM-040] RELEASE
• [CM-050] build management

Much more real world examples you find in the GitHub project TP-CORE.

Vocabulary Description

#INIT – the repository or a release.
    repro:documentation / configuration …
    archetype:jar / war / ear / pom / zip …
    version:version
#IMPLEMENT – a functionality.
    function:clazz
#CHANGE – a functionality.
    function:clazz
#EXTEND – a functionality.
    function:clazz
    attach:clazz
#BUGFIX – a functionality.
    priority:critical / medium / low / design
#REVIEW – an implementation.
    refactor:function
    analyze:quality
    migrate:function
    format:source
#RELEASE – an artifact.
    version:version
#REVERT – a commit.
    commit:id
#BRANCH – create.
    create:name
    stash:branch
#MERGE – from another branch.
    from:branch
    to:branch
#CLOSE – a branch.
    branch:name

Resume
There some blog posts about the essence of well written informative commit messages for SCM. Every one who was needed to investigate inside a SCM for rollback of particular changes, know how helpful declarative comments are. But in the other hand, as developer we are not famous for our documentation skills. The proposed solution offer beside the already mentioned benefits another one. The commit messages are standardized and with this defined vocabulary it is possible to process them automatically to gather several project information.