@eclipse313/conventional-commit-plus v1.0.0

Conventional-Commit Plus ✨

📘 Specification - 🤓 Cheat-Sheet - :octocat: Git Hooks - 🚓 Commitlint

Conventional-Commit Plus is a round-up of my accumulated knowledge on the subject of commits. The project is on the one hand a cheat sheet with all the information I have gathered on this topic and consider useful. On the other hand this is a package that can be used to configure Commitlint. The structure proposed here is a marriage of Conventional Commits and Gitmoji.

The following topics will be covered:

• General information about Conventional Commits
• What is the benefit of Conventional Commits (Plus)?
• The specifications of Conventional Commits Plus
• Cheat-Sheet: available types for commits ← Probably you are looking for this
• Automatic emojis with Git Hooks
• Automatic linting with commitlint
• A few words in closing

After following this guide, you may have beautiful commit messages in your repository that follow the well machine readable and widely used Conventional Commits but are still as nice to look at as Gitmoji. By using Git Hooks, you won't incur any additional work and commitlinter will ensure high-quality commits across all contributors and you can generate automatic changelogs or use semantic versioning:

About Conventional Commits

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. Check out the specification for more informations. Conventional commits, for example, make it easy to create automated changelogs.

Besides conventional commits, there are also other approaches and attempts to generalize commit messages and make them easier to understand. Another approach to classify commits is Gitmoji. Here, instead of defined code words, emojis are used to categorize the commits.

Conventional commits define a certain structure of the commit message. An example of a commit using this structure might look like the following:

feat(api): allow provided config object to extend other configs

Personal option and motivation

I believe that it makes sense and is necessary in larger projects to agree on a uniform standard of commits. Conventional commits are widely used and easily readable by machines due to their simple structure. Gitmoji rather follows the approach to design the commits in such a way that they are visually distinguished from each other by the emojis. Here I see the big disadvantage that the emojis look nice, but their meaning is not as clear - especially if you are not familiar with it - as the types of conventional commits.

For this reason, I decided to bring together what I consider the best of both worlds and create this repository.

Why use Conventional Commits Plus

It is widely agreed that people can absorb information quickly, especially through visual stimuli.^1 This is my motivation to extend conventional commits with emojis and to transfer this visual component into commits. Furthermore, the claim is not to violate any rules of conventional commits in order to maintain full support and backwards compatibility.

Why use conventional commits in general?

The specification of Conventional Commits summarizes the advantages nicely:

• Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
• Automatically generating CHANGELOGs.
• Automatically determining a semantic version bump (based on the types of commits landed).
• Communicating the nature of changes to teammates, the public, and other stakeholders.
• Triggering build and publish processes.

Specification

Conventional Commit Plus extends the original specification to the following commit message structure:

<type>[optional scope]: <description> <emoji>

[optional body]

[optional footer(s)]

The original specifications are retained and are expanded as follows:

• The emoji MUST be present in every commit and MUST match the specified emoji of the type.

Example

So a complete commit message could now look like this, for example:

fix(api): prevent racing of requests 🐛

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: eclipse313
Refs: #123

Examples of shorter messages might be:

docs: correct spelling of CHANGELOG 📚

feat(lang): add German language ✨

Cheat-Sheet

Overview of available types

The types are oriented to Commitlint Config Commitlint Config, that in turn is based on the Angular convention.

Detailed description of types

Builds 🏗️

Type: build

Changes that related to the build system or external dependencies (example scopes: gulp, broccoli, npm), such as build scripts, package dependencies, and tools used to build the project. This can include changes to the build process, configuration files, and environment variables.

⬆️ Back to overview

Chores 🔧

Type: chore

Changes that are made to the codebase that don't modify the source code itself or the test suite.

⬆️ Back to overview

Continuous Integrations 👷

Type: ci

Changes that are made to the Continuous Integration (CI) system (example scopes: Travis, Circle, BrowserStack, SauceLabs). This can include updates to the configuration files, scripts, or other tools used to automate testing and deployment.

⬆️ Back to overview

Documentation 📚

Type: docs

Changes that are made to the documentation of the project. This may include updates to the user guide, API documentation, README files, and other forms of documentation.

⬆️ Back to overview

Features ✨

Type: feat

Adding a new feature to the project.

⬆️ Back to overview

Bug Fixes 🐛

Type: fix

Fix for a bug or issue in the project.

⬆️ Back to overview

Performance Improvements 🏎

Type: perf

A code change that improves the performance of the project.

⬆️ Back to overview

Code Refactoring ♻️

Type: refactor

A code change that neither fixes a bug nor adds a feature

⬆️ Back to overview

Reverts ⏪️

Type: revert

Used to indicate that a previous commit is being undone or reverted.

⬆️ Back to overview

Styles 🎨

Type: style

Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).

⬆️ Back to overview

Tests 🧪

Type: test

Indicate changes that add, modify, or remove tests.

⬆️ Back to overview

Uncompleted Changes 🚧

Type: wip

Is used to indicate that a commit is a work in progress and is not yet complete. It is generally used when a developer wants to save their work-in-progress changes in a remote repository, such as GitHub, but is not ready to commit the changes with a more specific commit message.

It's important to note that wip is not a conventional commit type, but rather a shorthand way to indicate that a commit is a work in progress.

⬆️ Back to overview

Initial commit

According to Gitmoji I suggest to use Initial commit 🎉 as message for the first commit in a new repository without specifying a type or further information.

⬆️ Back to overview

Automatic setup with Git Hooks

It is possible to automatically add the emoji to the commit message by using the unique relationship between type and emoji. So it is possible to write "normal" conversional commits and they will be adjusted automatically.

In the following a client-side Git Hook will be created which will automatically add the correct emoji to the commit-message depending on the type. A Git hook is a script that Git can run before or after certain events occur, such as committing changes or pushing code to a remote repository. Git Hooks allow developers to automate certain tasks, enforce coding standards, and perform checks to ensure that code meets quality and security requirements.

To set up the git hook, all you need to do is copy the commit-msg file (check out the source code) from this repository and put it in the .git/hooks folder of the project in question and give the file the necessary permissions to run automatically. This can be done by the following command when executed in the project folder:

curl https://raw.githubusercontent.com/eclipse313/conventional-commit-plus/main/commit-msg -o .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg

See this hook in action. Pay attention to the added emoji after the commit message based on its type:

Linting with Commitlint

Commitlint is a tool that helps enforce consistent commit message formatting in Git repositories. It provides a set of rules that can be used to ensure that commit messages follow a specific pattern and format. This helps improve the readability of the commit history and makes it easier to understand the changes that have been made to a project over time.

The nice thing is: the commit format with the final emoji from this repository is backwards compatible with the default settings of commitlint. If you want to learn more about commitlint check out their website.

It is possible to configure commitlint to check whether the format described in the specification is followed. To do this, you need to add this repository to your dev dependencies:

npm install --save-dev @eclipse313/conventional-commit-plus

Then you need to edit your commitlint configuration so that the extends array includes this repository:

// commitlint.config.js
module.exports = {
  extends: ['@eclipse313/conventional-commit-plus'],
};

After installation, three new rules are available and automatically activated:

• header-ends-with-emoji: Checks if the header of the commit ends with an emoji.
• header-ends-with-allowed-emoji: Checks if the header of the commit ends with one of the allowed emojis (see types supported).
• header-ends-with-matching-emoji: Checks if the commit header ends with the emoji matching the type (see types supported).

See commitlint with this configuration in action:

It is possible to disable and configure the rules as usual as described in the commitlint documentation:

rules: {
	"header-ends-with-emoji": [2, "always"],
	"header-ends-with-allowed-emoji": [1, "always"], // Set this rule to "warning"
	"header-ends-with-matching-emoji": [0, "always"], // Disable this rule
}

Concluding remarks

I didn't think anyone would read this far. If you have any questions or suggestions, feel free to open issues in the repository. I appreciate feedback and suggestions for improvement.

– Thomas

^1: Rohrer, M. W.: Seeing is believing: the importance of visualization in manufacturing simulation. In: 2000 Winter Simulation Conference Proceedings (Cat. No.00CH37165). WSC 2000, Winter Simu- lation Conference, 10-13 Dec. 2000: IEEE, 2000, S. 1211–1216