The Elegant release process is fully automated. To make this work, all commit message must adhere to a given set of rules.

Why Have Commit Message Rules?

From the semantic-release project:

semantic-release uses the commit messages to determine the type of changes in the codebase. Following formalized conventions for commit messages, semantic-release automatically determines the next semantic version number, generates a changelog and publishes the release.

What does that mean? It means that semantic-release parses the commit messages to arrive at a unbiased version number for a new release, and then creates that new release. This allows for a new release to be put together with little human involvement.

What are those rules?

The Elegant development team chose to use the Angular Commit Message Conventions as the baseline for the team’s commit message conventions.

Our conventions are largely derived from the Angular team’s guidelines as documented here.

Is There Something to Help Me With The Rules?

Reading, understanding, and then getting used to following guidelines may take time. Even then, if you are in a hurry, you can sometimes forget what the rules are. It’s only human.

Our team has found life easier since we started using Commitizen for Git commits. Our project includes configuration for Commitizen that automatically formats each commit message to conform to our guidelines by walking you through a series of prompts. When you finish those prompts, a new commit messages is authored for you with the information from those prompts, following all of the rules in the following sections on the Commit Message Format.

Tip

Use Commitizen for Git commits. It does make life easier. It automatically formats the commit message to conform to our guidelines.

Commit Message Format

Each line of the commit message must be shorter than 101 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

Each commit message consists of a header, a body and a footer, as follows:

<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory. It has a special format that includes a required type, an optional scope and a required subject:

<type>(<scope>): <subject>

Type

The type must be one of the following:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing or correcting existing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
  • revert: A revert to a previous commit. See the section Revert Commits below.

Scope

The scope is intended to provide extra context on the changes included in the commit is for. This context should provide useful information to someone reading the commit log, including the reading of the commit log in the release notes.

For example, if you fix something in the authors blurb section, a scope of authors would be appropriate. If you are changing something with how the landing page works, a scope of landing page or home would be appropriate.

Subject

The subject part of the header must follow these rules:

  1. always use the imperative, present tense: “change” not “changed”, “changes”, or “changing”
  2. do not capitalize the first letter
  3. no period (.) at the end of the line
What is Imperative mode?

Chris Beams, in his article on how to write a good commit message, gives a very good explanation of imperative mode.

Imperative mood just means “spoken or written as if giving a command or instruction”. A few examples:

  1. Clean your room
  2. Close the door
  3. Take out the trash

The imperative can sound a little rude; that’s why we don’t often use it. But it’s perfect for Git commit subject lines.

Revert Commits

If the commit reverts a previous commit, it must be specified with the revert type, followed by the complete header of the reverted commit as the subject. The body of the commit must start with the text: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Body

The body of the commit message must follow these rules:

  1. always use the imperative, present tense: “change” not “changed”, “changes”, or “changing”
  2. include your motivation for the change and how it contrasts with the previous behavior

Breaking changes

All breaking changes have to be mentioned in the body with the description of the change, justification and migration notes. The body must be prefixed with the text BREAKING CHANGE:.

The following example is from the Elegant project repository. After the required prefix, it describes the problem it is solving, and why it was needed. In retrospect, while it does mention that LANDING_PAGE_ABOUT is no longer used, it should have gone into more detail on where to look up information on what was replacing it.

feat(home): write about me in markdown, reST or asciidoc

BREAKING CHANGE: Previously LANDING_PAGE_ABOUT was a dictionary that contained html tags. We used it
to create landing page. But users have demanded from the very beginning to be able to write the
landing page in markdown. This patch adds this feature. But in order to use it, you have to update
your configuration.

Closes #85

Referencing issues

Closed bugs should be listed on a separate line in the footer prefixed with the Closes keyword.

Closes #234

If your commit closes multiple issues, list them on the same line separated by a comma.

Closes #123, #245, #992

If your commit affects an issue, but does not fix it completely, use the “Updates” keyword

Updates #234

Correct Message Format Examples

The following are commits from our own repository that shows how Elegant has used these guidelines.

New Features

feat(monetization): add BestAzon support
feat(Chinese): add better font support for Chinese language
feat(footer): make external links Nofollow

Fixes

fix(reST): indents in line blocks is not preserved
fix(gist): embedded Github gist are not laid out correctly

Documentation

docs(add): metadata variables
docs(add): release notes for 3.0.0
docs(update): change category of reading-time article
docs(update): set author information

Miscellaneous

chore(livereload): use es2015 syntax for gulp configuration
ci(docs): use sitemap plugin in production only
ci(docs): add default tasks.py file
refactor: move Google and Bing claims to their individual files

Incorrect Message Format Examples

This commit message starts with a capital letter and ends with a period

doc(changes): Rewrite of multi-part plugin per issue 308.

This commit message does not use imperative mode.

docs(change): updating status doc to reflect current state

Like this post? Share on: TwitterFacebookEmail


Talha Mansoor Avatar Talha Mansoor is the creator and lead developer of Elegant theme.
Jack De Winter ever evolving, ever learning

Published

Last Updated

Category

Contributing

Stay in Touch

Get New Release Alert