contribute.md

Git Contribution Guidelines

This is a gist about general practices, rules and guidelines for team collaborators to contribute into git repositories.

How to write a git commit message

We have very precise rules over how our git commit messages must be formatted, rules that will give us uniformity and easier to read commit history.

Each commit message should consist of a three sections the header, the body, and the footer, where both the body and the footer are optional. The sections if applicable must be given in that order and should be separated each other by an empty blank line.

# Header
Summarize changes in around 50 characters or less (fixes #123)

# Body
More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Explain the problem that this commit is solving. Focus on why you are
making this change as opposed to how (the code explains that). Are there
side effects or other unintuitive consequences of this change? Here's
the place to explain them.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space, with blank lines in between, but conventions vary here

# Footer
If you use an issue tracker, add a reference(s) to them at the bottom,
like so:

Fixes #123

Header

Starting with the header, this is a mandatory section which must conform to the following format.

<verb> <scope> <summary> [fixes (#<issue>)]

The <verb>, the <scope> and the <summary> fields are mandatory and should form together a complete phrase describing the commit in the most compact way. The verb must be a clear indication of the action taken by this commit. The scope should point to what this commit applied for, which could be either a part of the project like a file, method, module or even a more abstract entity like a service. Last but not least the summary, which could be any free text that completes the message providing more information about the changes. The scope and the summary could be given in any order but the verb must always come first in imperative form.

If this commit relates to a ticket or a story on an issue tracker, the <issue> number must be given within parens at the end of the header. In case the commit fixes the issue the number must be prefixed as (fixes #123). If the commit resolves a story then the number must be prefixed as (resolves #123) instead. A more general case is when the commit doesn't resolve or fix anything but just relates to a issue, in this case you have to use the form (refs #123).

A long list of what the <verb> could be is given bellow:

• Fix, Resolve, Patch
• Add, Implement, Create
• Remove, Deduct, Deprecate, Drop, Delete, Dedupe
• Update, Modify, Extent, Convert, Transform
• Refactor, Move, Replace, Unify, Rename, Migrate, Split, Decouple, Switch, Swap, Hide, Expose
• Encapsulate, Wrap, Embed, Include, Exclude, Import, Export
• Improve, Optimize, Simplify, Clean up, Secure, Lint
• Validate, Check, Avoid, Allow, Disallow, Relax, Restrict, Ensure, Prevent
• Use, Set, Reset, Enable, Disable, Increase, Decrease, Limit, Enforce
• Format, Style, Decorate, Adjust, Align, Escape, Mark
• Upgrade, Bump, Lock
• Handle, Catch, Invoke, Call, Parse, Get, Fetch,
• Join, Cut, Attach, Detach, Link
• Start, Stop, Run, Defer, Delay, Skip
• Comment, Document, Clarify
• Test, Assure

Note this is a list of commonly used verbs, any verb could be adequate if clarifies the purpose of the commit.

The <scope> should be a noun refering to anything in a project from an abstract part to a more specific file. Below you can find a short list of examples as they are used in real world cases:

• method, function, service, module, route, endpoint, option
• feature, implementation
• bug, typo, style, format
• deps, library, package
• performance, complexity, readability
• config, script, task, file

Note that this is a list of commonly used nouns, any noun could be adequate if points to the real target of the commit.

The <summary> together with the <verb> and the <scope> should form a complete sentence providing a succinct description of the change. The following rules must be followed for the whole message:

• Use the imperative, present tense: "Fix" not "Fixed" nor "Fixes"
• Capitalize the first letter
• Do not use dot (.) at the end
• Don't use emoji icons or special characters like => and so on
• Keep it 50 characters long

Optionally you can emphasize that a commit is made under a chore task, so feel free to use the word minor in order to emphasize that this is a not critical change, e.g. Fix minor typos in comments.

Body

The body is an optional free text content and must be provided only if there is need for more explanation about the changes. When the body is present each line must be wrapped within 72 characters and must conform to the following practice.

Explain the motivation for the change in the commit message body. This commit message should explain what this change is about and why you are making the change and not the how. You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.

In the case the commit is about a breaking change this section should start with the phrase BREAKING CHANGE: followed by a detailed description of the breaking change that perhaps includes migration instructions.

Footer

The footer is optional and when it is present can contain information about the place to reference GitHub issues, Jira tickets, and other PRs that this commit closes or is related to in the following form.

<verb> #<issue>

The <verb> should come before the <issue> number and be one of the following verbs,

• Fixes: The commit fixes the issue, e.g. Fixes #123
• Resolves: The commit resolves the issue, e.g. Resolves #123
• Refs: The commit doesn't fix or resolve but is referencing to the issue, e.g. Refs #123

Bear in mind that's not a good practice a commit to refer to more than one issues.

What information to put in commit messages

The followings are some of the information should be provided in a commit message:

• Describe why a change is being made
• What effects does the patch have
• Do not assume the reviewer understands what the original problem was
• Do not assume the code is self-explanatory
• 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