Git Commit Conventions - PrajaktaLandge9/git-commit-conventions GitHub Wiki

Git Conventional Commits

  • Conventional commits are the specifications for commit messages so as their meaning can be understood by machines and humans.
  • It is a way to format the commit messages.

Semantic Versioning ( SemVer )

  • Convention to structure your commit messages is based on semantic versioning (SemVer)
  • Version of a software denotes the fact that something in the software is changed.
  • 'Semantic versioning goes a step further and allows you to estimate how big that change is'. By this, You can make a judgment call, Whether to upgrade to a new version of the library or not.

Structure of a commit message

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Using this commit structure impacts the project development and quality of commit messages.

The description of each element in the message structure is as follows :

type :

It is written to communicate the intent of your change.

The most commonly used types are :

  1. fix : A change for bug fixes.It correlates with PATCH in Semantic Versioning.

  2. feat : A change for code features.A feature that is visible for end users. It correlates with MINOR in Semantic Versioning

  3. chore: a change that doesn't impact end users.

  4. docs: a change in the README or documentation

  5. refactor: a change in production code focused on readability, style and/or performance.

scope:

  • Scope is any additional information.
  • It specifies what you changed, Preferably in a single word.
  • A scope is provided to a commit’s type within parenthesis
  • Writing scope is optional
  • Use nouns for writing scope e.g. feat(parser): add ability to parse arrays

description :

  • It contains a short message that describes what the commit does.

  • It should be written in an imperative tone. Eg. write add instead of adds or added.

  • Descriptions are written as if giving a command or instruction.

  • It is also called the summary portion of the commit message.

  • Begin description with a capital letter.

  • Do not end the description with a period.

  • Limit the description to 50 characters.

optional body :

  • Body of the commit message explains what changes you have made and why you made them.

  • It follows description with one blank line and is written in free form using regular sentences, Regular paragraphs.

  • Wrap the body with 72 characters.

  • Not all commits are complex enough that they need a body.

optional footer :

  • Footer is used to tag relevant issues or pull requests.

  • It follows the body with one blank line.

  • A commit that has a footer BREAKING CHANGE , or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.

  • You can also use footers for metadata such as what type of method you used for developing the code.

  • Footers are mainly written when you are using the issue tracker to refer to the issue ID.

Whenever you have a breaking change, Instead of a footer, You can also give an exclamation mark ‘!’ after type or scope and highlight the change in the description.

An example of a 'conventional commit' :

git commit -m "feat(feedback): added the ability to add feedback.

This has been a feature requested by different users. Changes in the database structure where necessary to make this happen.

Resolves #Issue Id

The seven rules of a great Git commit message :

  1. Separate subject from body with a blank line.

  2. Limit the subject line to 50 characters

  3. Capitalize the subject line

  4. Do not end the subject line with a period

  5. Use the imperative mood in the subject line

  6. Wrap the body at 72 characters

  7. Use the body to explain what and why vs. how

Why are these conventions important to follow ?

  • In 2011, Tom Preston-Werner came up with a suggestion for naming versions of softwares so as to maintain the code and changes done in the code, And project becomes self explanatory, Thus the developers started using conventional commits in order to have a more structured commit history.

  • Conventional commits are used to write a good and more descriptive commit message.

  • Good commit messages are important for maintaining any long-term project.

  • Commit messages will help you keep track of your commits and will help in identifying what changes were made with each commit.

  • A well-crafted git commit message is the best way to communicate context about a change to fellow developers working on the project.

  • By following the conventions; reviewing others' commits and pull requests becomes easy and saves time and also allows multiple developers to contribute to a project leading to faster development.

  • A good commit message explains why and what problem the commit is solving.

  • As the conventions make the commit message computer readable and understandable, we can automate things, Such as automatically generating CHANGELOGs.

⚠️ **GitHub.com Fallback** ⚠️