Webdevelop Docs

Appearance

Git commit message ​

Commit Message Format ​

Each commits message consists of a header, a body and a footer. The header has a special format that includes a type and a subject, and link to the ticket:

<type>: <subject>
<org-name>/<project-name>#<ticket-id>
<BLANK LINE>
<BLANK LINE>
Short (72 chars or less) summary
More detailed explanatory text. Wrap it to 72 characters.
<BLANK LINE>
line separating the summary from the body is critical (unless you omit the body entirely).
<BLANK LINE>

Further paragraphs come after blank lines.

The subject is mandatory and the type of the header is optional.

Important:

Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug."
This convention matches up with commit messages generated by commands like git merge and git revert.

Example for a commit message ​

feat: 245 Add plaid identity functionality
webdevelop-pro/general#245


This code is an initial version of the plaid identity integration
to get user first and last name and prevent of fraudulent action

Example usage:
`GET user-api-dev.example.com/plaid/verify authorization: JWT`

Rules for a great git commit message style ​

  • Separate subject from body with a blank line
  • Do not end the subject line with a period
  • Capitalize the subject line and each paragraph
  • Use the imperative mood in the subject line
  • Wrap lines at 72 characters
  • Use the body to explain what and why you have done something. In most cases, you can leave out details about how a change has been made.

Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines.

fix: 3357 Fix Payment Method For Entities Distributions
webdevelop-pro/general#3357


BREAKING CHANGE: Distributions API call must include entity type
Before `POST investment-api/distribution amount=123`
After `POST investment-api/distribution amount=123 **type=<type>**`

This code deploys fix for the distribution payments for entities

Use the imperative mood in the subject line ​

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

  • Clean your room
  • Close the door
  • Take out the trash

Writing this way can be a little awkward at first. We’re more used to speaking in the indicative mood, which is all about reporting facts. That’s why commit messages often end up reading like this:

  • Fixed bug with Y
  • Changing behavior of X

And sometimes commit messages get written as a description of their contents:

  • More fixes for broken stuff
  • Sweet new API methods
  • To remove any confusion, here’s a simple rule to get it right every time.

A properly formed Git commit subject line should always be able to complete the following sentence:

If applied, this commit will your subject line here For example:

  • If applied, this commit will refactor subsystem X for readability
  • If applied, this commit will update getting started documentation
  • If applied, this commit will remove deprecated methods
  • If applied, this commit will release version 1.0.0
  • If applied, this commit will merge pull request #123 from user/branch

Notice how this doesn’t work for the other non-imperative forms:

  • If applied, this commit will fixed bug with Y
  • If applied, this commit will changing behavior of X
  • If applied, this commit will more fixes for broken stuff
  • If applied, this commit will sweet new API methods

Remember: Use of the imperative is important only in the subject line. You can relax this restriction when you’re writing the body.

Information to insert into commit messages ​

  • Describe why a change is being made
  • How does it address the issue?
  • What effects does the patch have?
  • Do not assume the reviewer understands what the original problem was
  • Do not assume the code is self-evident/self-documenting
  • Read the commit message to see if it hints at improved code structure
  • The first commit line is the most important
  • Describe any limitations of the current code
  • Do not include patch set-specific comments

References in commit messages ​

If the commit refers to an issue, add this information to the commit message header or body. The GitHub web platform automatically converts issue ids (e.g. organization/repo#123) to links referring to the related issue.

References ​