a bunch tell // team

#BestPractices for working with git on Write.as projects.

Make multiple, granular commits. Work on small, concrete pieces of the task at hand. Then, when you've completed a usable chunk of code, use git add -p to step through your changes and commit only the ones that complete that certain bit of functionality. Often, this will result in creating multiple commits — even very small ones. That's okay!

Small commits make everyone's lives easier, from other developers to regular people scanning through the code. Doing so:

• Makes it easy to read through a log of changes in plain English, and quickly understand the decisions made over time without having to dig into code
• Makes it easy to use the git blame tool, to figure out why a certain change was made when looking it up from a line of code
• Makes it easy to revert decisions for any reason. Rather than the error-prone process of going into the code and undoing your changes, you can just do git revert [commit-hash]

Some examples of granular commits:

Fix file indentation
Run goimport on project
Fix Docker build after enabling Go modules
Include --config step in `make install`

Write good commit messages. Once you've started making granular commits, you'll want to ensure their messages are easy to understand and consistent with the rest of the project.

The first line of your commit message should concisely sum up the changes in your commit, ideally in under 75 characters. If that's not possible to do, that could be an indication that your commit contains too many unrelated changes, and should be broken up.

As for how to write the commit message, follow the advice given in the Git book:

Write your commit message in the imperative: “Fix bug” and not “Fixed bug” or “Fixes bug.”

After that short, initial line in your commit message, you can optionally explain your changes in more detail below it. That may include:

• Rationale for any decisions made
• What other parts of the software are affected by the change
• What existing behavior changed
• References to GitHub issues, e.g. Fixes #19 or Part of #13, or Phabricator tasks, e.g. Fixes T123 or Ref T234

Don't force-push. Force-pushing creates headaches for other developers when they pull your code. Instead of force-pushing, create new commits, revert commits, and generally use the other git tools available to you to accomplish what you need to.