Template and guidelines for git commits

[rudimusmaximus]

objective / purpose
Formalize git commit style for DevFlow.

completion checklist

• Discovered in: 0.2.0
• Resolved/introduced in: n/a issue only no code change
• Design Ready - labels, estimates
• Development Ready - design and change list created, updated complexity label and estimates
• Changes Listed (mark each member as completed update as needed)
  • Update contributing.md with design notes below
  • Upload a file for use in dev's default git message
  • Add checklist item to default issue checklist from issues.md
  • Add automation to enforce Commit Message Standards see How can we Automate git commit message standards enforcement #44
• n/a Developer Tested - Test Copies (Disposable Alpha "DA!s" and Release Candidate)
• new item (see notes)

POST LIVE:

• n/aBeta Tested - Live to controlled audience  
• n/aCustomer Experience - Live analytics reveal working for customers  
• currently manual as part of PR review and own PR submitter's habits review with issue How can we Automate git commit message standards enforcement #44

full pipeline documentation

Overview - describe with history and related items

Referencing style guides for Udacity nanodegree front end web developers, modify contributing.md with an adapted template for DevFlow. These are not automated, so add a check for consistency in the default issue lifecycle.

See these from Udacity course notes:

• Google Javascript Styleguide
• Udacity CSS Style Guide
• Udacity HTML Style Guide
• Udacity JavaScript Style Guide
• Udacity Git Style Guide

Solution Design

Adapted from Udacity Git Style Guide for this DevFlow.

issues.md

We need this new checklist item in the issue lifecycle.

• Pull request review should verify Commits follow style guidelines in contributing.md PRIOR to code merge

contributing.md

Add a section in contributing based on Git commit style guide above.

type: subject

body

footer

WHERE subject is mandatory and the rest optional based on content.

where repo uses git flow and semantic versioning inside codebase namespace.

EXAMPLE modified from Udacity

feat: Summarize changes in around 50 characters or less

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 the commit 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); various tools like `log`, `shortlog`
and `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, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123 [DO NOT use GitHub issue close language if running sprints using ZenHub Here]
See also: #456, #789

What's New Entry

n/a  

Solution Implementation Notes

Note when using GitFlow and our DevFlow label scheme with this new commit style guide, we have three different schemes of classifying changes each with its own purpose and we can make the case for each being equally valid. We will do all three. Listed here for clarity.

GitFlow Branch types	Git Commit subject line types	Issue Label Scheme
feature, release, hotfix	feat, fix, docs, style, refactor, test, chore	The relevant portion of our label scheme would be: DOCUMENTATION, admin-bug, admin-duplicate, admin-enhancement, admin-invalid, admin-optimization, admin-question/assignment Plus the other DevFlow labels as dictated in CONTRIBUTING.MD guidelines

Developer Testing- Disposable Alpha and Release Candidate

Live Testing - Beta live to a controlled audience

Customer Experience - Re-open and append if issues for customers

• REMOVE signature concept per G+ discussions and testing, also remove sem ver in commits; they are mostly annotated with user. Difference comparisons between tags can show sem ver in files to go further if needed, but this depends on make test ready approach and sem ver in the namespacing.

[rudimusmaximus]

Feedback sought with links to this issue:

• on private slack team
• on G+ community

Agree on removing sem ver and signature from message format.

[rudimusmaximus]

subjectLineType: Summarize changes in around 50 characters or less

Subject line types are
feat, fix, docs, style, refactor, test, and chore.

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 the commit 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); various tools like log, shortlog
and 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, preceded
  by a single space, with blank lines in between, but conventions
  vary here

If you use an issue tracker, put references to them at the bottom,
like this:

See also: #number, #anotherIssue OR no line at all

[rudimusmaximus]

This article explains how to setup your own global git commit message template or to do so locally for your repo.
article about git commit templates
code commit template

[rudimusmaximus]

The latest GitKraken allows for removing comment lines from your commit messages (these start with #). So, in your prefereces at least for one repo. it looks like this.

For info about setting globally see the links in the previous block.

[rudimusmaximus]

Updated version you can cut and past for subject and body of commit template

Subject line

subjectLineType: SummarizeChangesInAround50CharsOr

Body - copy from below below line to end of comment

---

#subjectLineTypes: { feat fix docs style refactor test chore }
#More detailed explanatory text, if necessary. Wrap it to about 72
#characters or so.

#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, preceded

by a single space, with blank lines in between, but conventions

vary here

#If you use an issue tracker, put references to them at the bottom,
#like this:

#See also: #number, #anotherIssue OR no line at all

[rudimusmaximus]

My current default git commit is

subjectLineTypes: { feat fix docs style refactor test chore }
# More detailed explanatory text, if necessary. Wrap it to about 72
# characters or so. 
#
# 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 non-intuitive 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, preceded
#  by a single space, with blank lines in between, but conventions
#   vary here
#
# If you use an issue tracker, put references to them at the bottom,
# like this:
#
# Resolves: #123 [DO NOT use GitHub issue close language if running sprints using ZenHub Here]
# See also: #number, #anotherIssue OR no line at all

use this with the subject moved into the subject line and tell GKraken to remove # comment lines