Definitive Guide to Structuring Commits

Commit format

Each commit consists of three different elements, as below:

• Header - Required, this is basically the title of your commit
• Body - A more extensive description of the information you intend to convey with your commit
• Footer - If there is a ticket or issue, you can report it here

Both the Body and the Footer are optional, and as far as I can see, they are generally not used much.

Header

The header must maintain a predefined pattern, containing a type, a scope (only when applicable), and a title, and for faster and simpler reading and understanding, it must not exceed 50 characters.

{type}({scope}): {title}

Examples:
fix(login redirect): prevent redirect to external url
feat(middleware): refuse connections from other hosts on production
refactor(markdown viewer): prepared for future viewer package change
fix: serve HomeOffline and remove SWR fetch
fix(query): performance with large offset


These examples were selected from the list of commits in the official TabNews repository.

Did you notice how simple and objective they are? Any developer who has never even seen the repository before in their life, by reading these commits can already have a minimal idea of what the subject is about, and that is precisely the objective I want to achieve with this post!

Type

Here is the real inspiration responsible for my decision to write this post.

The type of the commit says practically everything about it, being able to inform whether this commit is related to a correction in a line of code, the addition of a new feature, improvements, among others.

The type must be one of those listed below:

• build: changes that affect the build system and/or external dependencies
• static: changes to the content of static files (data .css, .js, .json, images, among others...)
• ci: changes to CI* configuration files and scripts
• cd: changes to configuration files and scripts for CD*
• docs: changes to the wiki and/or application documentation
• feat: a new feature or resource
• fix: referring to an application bug fix
• perf: code change that improves application performance and does not change the way the user uses the application
• refactor: code refactoring, which does not fix a bug or change the way the user uses the application, it just rewrites the code in a better organized and structured way
• improve: some code change that improves the behavior of an existing resource
• style: changes that do not affect the meaning of the code (white space, formatting/identification, semicolons, among others...)
• test: adding new tests or correcting existing tests (normally it is not necessary to use fix in this second case)
• revert: revert to a previous commit

In addition to these, we have of course the famous merge, which is in a different structure pattern but is generated by GitHub itself and we understand its importance in the same way!

* Important observation: Today I do not have full knowledge of what CI (Continuous Delivery) and CD (Continuous Deployment) are about. So if anyone already has one or wants to make a post about it, let me know the post's URL in the comments and I'll be proud to learn about it and also attach it to the two items marked above!

About revert

If the commit reverts to a previous commit, it must begin with revert:, followed by the header of the reverted commit.

If the body is used, it must inform: This reverts the commit {commit hash}

About the scope

The scope, in short, is what exactly you are working on in that commit, for example middlware, a login screen, a specific resource, among others.

About the title

The title should contain a summarized and succinct description of the change, and the ideal is to follow the rules listed below:

• Use the imperative, and in the present tense and never in the past, for example: "change", "amendment", "implementation", and never "changed", "altered", "corrected", etc.
• Do not capitalize the first letter, keep everything lowercase except when it is a proper name, a system or language (for example MySQL, PHP), in these cases keep the standard name of what you are using. For example: replacing MySQL database integration with PostgreSQL
• Do not use a period (.)
• When it is necessary to refer to a specific location, function or field of the application, it is recommended to use the tag code referring to the platform being used, in the case of GitHub it is the three backticks (```)

Below is a complete example:

fix(controller): use cf-connecting-ip header to get client ip first

Body

A longer description for your commit can be provided right after the title, in a separate field, providing additional contextual information about your commit.

Break lines at least every 72 characters for better reading.

Use this description to explain "what" and "why" this change was made, rather than "how."

Baseboard

The footer may be provided below a blank line after the body.

You can use it to reference a ticket in Jira, a task in Asana or Perfex and other helpdesks, or even an issue on GitHub itself, as in the example below:

fixes issue #12

And why all this?

These are some possibilities and advantages that we gain when committing in an organized and succinct way:

• Automated creation of CHANGELOGs
• Automatically determines a semantic versioning increase based on the commit types used
• Communicate to other employees and interested parties the nature and reason for the change, in a clear and standardized way
• Trigger build and deploy processes
• Makes it easier for other people to contribute to your projects, allowing them to explore a more structured commit history with better traceability and understanding