Awesome Semantic Commit: Guide to regular commit messages

Star on GitHub

Semantic Commit?

Semantic Commit is a method used in software development. Its main purpose is to ensure that commit messages (i.e., messages associated with each change made to the code) are more meaningful and structured. This way, developers can more easily understand when, why, and what changes were made to the code.

Why Is It Important?

Easily Understandable Changes

Each commit message clearly describes the changes made. This way, while working on a project, you can quickly understand what changed in the code and why. For example, instead of saying 'just some edits made,' a clear explanation like 'new login page added' is provided.

Faster Issue Resolution

When there is a bug in a project, it becomes much easier to find the changes that might have caused the issue by reviewing past commit messages. Meaningful and structured commit messages help you quickly locate and resolve errors.

Version Tracking

Semantic Commit helps you see more clearly which changes were made in which version of the project. For example, when a new feature is added, the version number can be updated. This makes it easier to keep the project up to date.

Team Collaboration

When working with multiple people, having everyone write commit messages in the same way keeps the project organized. This way, one team member can more easily understand what another has done, increasing collaboration.

Easier Project Management

As the project grows, there may be hundreds or even thousands of commits. Meaningful commit messages make it easier to manage the large project and track changes over time.

Commit Message Structure

Semantic Commit messages are written according to a specific rule. These rules make the structure of each commit message meaningful and consistent.

1. Type

This indicates the type of change made. It is added at the beginning of the commit message. Common commit types include:

feat

Used when a new feature is added.

fix

Indicates that a bug has been fixed.

docs

Used if only documentation-related changes are made.

style

Changes that do not affect the code's functionality, only related to formatting (e.g., correcting spaces or punctuation).

chore

Non-functional changes to the code or dependencies. For example, package updates or changes in build configurations.

refactor

Used to restructure the code without changing its functionality.

test

Used to add or update tests.

perf

Used for changes made solely to improve performance without altering the functionality. This includes improvements like making the code run faster, reducing resource consumption, or increasing efficiency.

Used for changes related to continuous integration configuration. For example, changes to the CI/CD pipeline.

build

Used for changes related to the build system, such as build settings or dependency management.

revert

Reverts the effects of a previous commit.

2. Scopeoptional

Specifies which module, file, or component the change was made on. It is written in parentheses along with the type.

feat(auth),fix(ui),docs(readme),style(header),chore(deps),refactor(api),test(login),perf(image-loader),ci(travis),build(webpack),revert(api)

3. Subject

Briefly and concisely describes what the commit does. It should be written in a maximum of 50 characters.

feat(auth): add login functionalityfix(ui): resolve button alignment issuedocs(readme): update installation instructionsstyle(header): fix indentationchore(deps): update axios to v0.21.1refactor(api): optimize fetch methodtest(login): add unit tests for login functionperf(image-loader): optimize image loading for faster page speedci(travis): add deployment step to pipelinebuild(webpack): update webpack configuration for faster buildsrevert(api): revert API changes that caused issues with data fetching

How to Use?

1. Staging Changes

First, after making changes to the files you're working on, you need to use the `git add` command in the terminal to include these files in the commit.

To add all files, enter the following command in the terminal:

git add .

If you only want to add specific files:

git add <file-name>

2. Making a Commit

To commit the changes, you can use the following command in the terminal:

git commit -m "<commit-message>"

When writing a commit message that follows the Semantic Commit rules, here are the key things to pay attention to:

Commit Type: Indicate the type of change made (e.g., feat, fix, docs, etc.).
Scope (Optional): You can use scope to specify which module or component was changed.
Message Title: Briefly and concisely describe the change.

Example commit:

git commit -m "feat(auth): add user login functionality"

3. Pushing the Commit

After making a commit, you can push your changes to the remote repository using the following command in the terminal:

git push origin <branch-name>

For example, if you're pushing to the main or dev branch:

git push origin main

How Not to Use?

1. Commit Messages Should Only Be in English

Why? English is considered a global language in the software world. Developers and teams from different countries communicate in English during coding and in commit messages. Therefore, commit messages should also be in English.

Commit messages written in Turkish or other languages can confuse people working in international teams or on open-source projects and make collaboration more difficult.

Wrong Usage:

eklenen özellik,güncellenen sayfa,değiştirilen kod

Correct Usage:

feat: add new search feature,fix: update login page,refactor: improve validation logic

2. Why Should We Avoid Using Words Like 'added', 'updated', 'changed'?

There is no need to use these words to indicate commit types, as the commit types already convey this meaning. Types like `feat`, `fix`, and `refactor` already specify the purpose of the changes, so there is no need to repeat words like 'added', 'updated', or 'changed'.

Wrong Usage:

feat: added new button,fix: updated validation,refactor: changed structure

Correct Usage:

feat: add new button,fix: improve validation logic,refactor: change component structure

3. Incorrect Type Usage

Using an incorrect label in the commit message that does not match the type of change made. Each type serves a specific purpose, and incorrect type usage can make it unclear what the changes are for. This situation can make it difficult for the project team to track changes and complicate code management.

Wrong Usage:

fix: add user authentication,feat: fix payment gateway issue,fix: optimize the code

Correct Usage:

feat: add user authentication,fix: payment gateway issue,refactor: optimize the code

4. Unnecessary Use of Capital Letters or Special Characters

The use of capital letters or special characters in commit messages, either accidentally or intentionally, that disrupts the readability and consistency of the messages. Such usage can cause commit messages to lose their professionalism and alignment with standards.

Wrong Usage:

FEAT: NEW LOGIN SYSTEM IMPLEMENTED!!!,FIX: NULL POINTER EXCEPTION FIXED,REFACTOR: IMPROVED CODE PERFORMANCE!!!

Correct Usage:

feat: implement new login system,fix: resolve null pointer exception,refactor: improve code performance

Projects Using Semantic Commit

Semantic Commit

semanticcommit.com

Learn best practices for clear, concise commit messages to improve project organization, code readability, team collaboration, and version control.

React

react.dev

React enables the development of dynamic user interfaces with reusable components, enhancing performance and efficiency in web applications.

Next.js

nextjs.org

Next.js allows you to build full-stack web applications using React's latest features and fast Rust-based JavaScript tooling, used by many large companies.

Vue.js

vuejs.org

Vue.js enables dynamic user interfaces with reusable components, enhancing performance and efficiency.

freeCodeCamp

freecodecamp.org

freeCodeCamp is a nonprofit platform offering free coding lessons and resources for web development and data science.

Bootstrap

getbootstrap.com

The most popular HTML, CSS, and JavaScript framework for developing responsive, mobile first projects on the web.

Frequently Asked Questions

1. Understandability: Each commit message clearly states the purpose and reason for the change. For example, a message like "feat: Added new user login page" indicates that this commit was made to add a new feature.
2. Tracking the Code History: If a project has many developers working on it, each commit message makes the project’s history more transparent and easier to track. Knowing when a change was made helps in finding and fixing bugs.
3. Versioning and Automation: Semantic commit messages can help with automatic version updates (e.g., adding a new feature, fixing a bug). These messages make it easier to increase version numbers in an organized way (e.g., 1.2.0 → 1.3.0).

Each commit message should clearly express the purpose of the change. This helps other developers in the project to easily understand the reason for the changes. A good commit message avoids general terms like 'bug fix' or 'feature update' and clearly states what has been improved or fixed. Commit messages should also be concise. If necessary, additional explanations or references can be added after the commit message.

There are several methods to undo a commit:
Undo the last commit (soft reset):
git reset --soft HEAD~1
* This command undoes the last commit but leaves the changes in your working directory.
Completely undo the last commit (hard reset):
git reset --hard HEAD~1
* This command deletes both the commit and the changes.
Undo using the git revert command:
git revert
* This command undoes a specific commit and creates a new commit.