doc(wiki): add guidelines for Git communication

[kevinwhoffman]

Issue Overview

As we look to modernize the Give pipeline, I’d also like to propose some guidelines for Git commit messages that will help create more consistent and informative Git logs. If the team agrees, we could move these guidelines to CONTRIBUTING.md.

The seven rules of a great Git commit message

The inspiration for these guidelines can be summarized in the following 7 points:

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

Emphasize Why instead of How

In most cases, you can leave out details about how a change has been made. Code is generally self-explanatory in this regard (and if the code is so complex that it needs to be explained in prose, that’s what source comments are for). Just focus on making clear the reasons why you made the change in the first place—the way things worked before the change (and what was wrong with that), the way they work now, and why you decided to solve it the way you did.

Example

You can see an example of consistent formatting in the WPBR commit history.

I've been following these guidelines for a few years. While I need to do a much better job of explaining the why, I find the formatting alone makes for better Git logs that are easier to scan over time.

Considerations

Consistently formatting commit messages is an easy win. The more challenging task with these type of guidelines is balancing clarity with efficiency. After a few weeks I think it will become second nature as it did for me. Interested to hear your thoughts.

[ravinderk]

@DevinWalker We can use default git message template to improve commit message. For Ref: https://robots.thoughtbot.com/better-commit-messages-with-a-gitmessage-template

Most of editor use git message template.

Source Tree

Atom

[malayladu]

I agree with @kevinwhoffman on emphasize Why instead of How.

People can easily see How it's done but it's hard to understand Why it's done.

@ravinderk suggested a good point too. Using commit message template to describe Why & How would be a great deal like we follow issue template while creating a new issue on repository.

[kevinwhoffman]

Edit: This content has been moved to the Git Communication Standards section of the Wiki.

[kevinwhoffman]

Per discussion with @DevinWalker and @ravinderk, I'll be moving these guidelines into the Give Wiki. Once the Wiki is built out, it can be linked to from the README.md and/or CONTRIBUTING.md.

Tasks

• [x] Complete the initial set of Git Communication Guidelines to separate Wiki pages
  • [x] Overview
  • [x] Prefixes
  • [x] Issues
  • [x] Commits
  • [x] Pull Requests
• [x] Migrate the above guidelines to separate Wiki pages
• [x] Enhance the Guidelines with further documentation of the following topics.
  • [x] Sprints (aka Milestones)
  • [x] Epics
  • [x] Releases
  • [x] Labels
  • [x] Story Point Estimates
  • [x] Branch Management
  • [x] Pipeline Management (ZenHub boards)
  • [x] The Role of Slack

[kevinwhoffman]

Closing as the Development Handbook in the Wiki covers all of the above topics.