Git on Steroids

1. Logs fail to accomplish their purpose:

   Usually, due to vague or incomplete commit messages, a commit message log can only be understood by the one who wrote it (just like it happens with source code), thus making the log useless.

2. Reverting becomes a headache:

   If there is not a clear history of your repo, reverting to a previous version given the need will always be painful, as you will have to decipher such history in order to know to what point you want to go back.

3. Knowing who did what becomes harder:

   Good commit messages express, from a high level perspective, what changes were made. Not-so-good commit messages usually have two or three words and do not actually tell the reader what was changed, forcing him/her to look at the source code.

1. Data Analytics for the repo becomes possible:

   When you have one hundred developers working simultaneously on a repository, you definitely want to know things like:

   • What percentage of time do they spend fixing bugs?

   • What percentage of the programmers focus on creating new features?

   • What are the main causes of reverts in the repo?

   And an endless number of questions whose answers might be incredibly useful for both business insights and development performance/quality improving within the company. By having a defined commit message syntax, such answers can be found by using Data Analytics techniques

2. Logs (partially) become your documentation:

   By standardizing commit messages, you will no longer have to create huge documentation manuals explaining all the details of how a product internally works. Each file within the repo will have its related history with detailed information about how it currently works and worked in the past. Some documentation will probably still be needed (user documentation, for example), but we have witnessed how the amount of documentation required dramatically diminishes thanks to good logs.

1. Titles include keywords like feat, front, fix, doc…​ These tags will be essential for the Data Analytics efforts, as they will allow algorithms to know what the purpose of the commit was.

2. Body section is usually itemized, with every item describing relevant changes made in the commit.

3. An issue (#N.N) is always referenced with the purpose of understanding what the programmer was trying to do with the commit. This is useful for version control services with issue trackers like Gitlab, Github, etc.

  [type]([scope]): #[issue-number]{.issue-part} [title] // This is the commit title
                 // This blank line separates the commit title from the commit body
  [body]         // This is the commit body. It CAN have multiple lines

• [variable] are required variables that must be replaced in a final commit message ([] symbols must be removed).

• {variable} are optional variables that must be replaced or removed in a final commit message ({} symbols must be removed).

• // Comment are comments that must be removed in a final commit message.

  rever  // Revert to a previous commit in history
  feat   // New feature
  perf   // Improves performance
  fix    // Bug fix
  refac  // Neither fixes a bug or adds a feature
  test   // Adding missing tests or correcting existing tests
  style  // Do not affect the meaning of the code (formatting, etc)

    front  // Front-End change
    back   // Back-End change
    infra  // Infrastructure change
    conf   // Configuration files change
    build  // Build system, CI, compilers, etc (scons, webpack...)
    job    // asynchronous or schedule tasks (backups, maintenance...)
    cross  // Mix of two or more scopes
    doc    // Documentation only changes

1. A Commit title must exist.

2. A Commit title must not contain the ':' character aside from the one specified in the syntax.

3. A Commit title must have 50 characters or less.

4. A Commit title must be lower case.

5. A Commit title must not finish with a dot '.'.

6. A Commit title must reference an issue.

7. A Commit title must be meaningful. Avoid using things like feat(build): #5.1 feature.

8. A blank line between commit title and commit body must exist.

9. A commit body must exist.

10. Lines in commit body must be 72 characters or less.

11. Try to itemize your commit body.

12. Do not use the word 'part' for splitting commits for a single issue. Use #[issue-number]{.issue-part} instead as specified in the syntax.

• perf is performance.

• infra is infrastructure.

• config is configuration.

• doc is documentation.

• NA is not applicable.

1. Instead of creating a particular syntax only for reverts as specified in the AngularJS' document, for the sake of simplicity, we decided to make a rever type that follows the same syntax as everything else.

2. The docs type was renamed to doc and turned into a scope. The reason of such change was to make doc commits more informative by allowing programmers to specify the purpose of the documentation change. For example:

   • feat(doc): documenting new feature.

   • fix(doc): fixing documentation.

   • style(doc): changing its style.

3. We added a perf type for performance changes with the purpose of identifying what commits have a performance improvement as main objective and reducing the number of commits that would fall under the refac type.

4. chore type was removed as any maintenance commit can be translated to a perf/refac/fix commit.

5. In order to have shorter commit titles, we shortened types like docs to doc, revert to rever, refactor to refac.

• What type/scope combinations were mostly used.

• What type/scope combinations were never used.

• In general, we can get insights about what programmers did and where they did it.

1. What do we want to know?

2. Can we know it with the data we currently have?

• Product