Git Hygiene

Some guidelines for keeping your code in shape

1. Use the diagnostics from gulp test (tests are also run as part of gulp dev and any changes to a file are also tested if gulp dev is currently running). It's much easier to stay on top of issues as you make changes than trying to fix everything later. If you have gulp dev running, it can also sometimes be useful to run gulp test in a separate process, which will analyze every file, and is the same tests that Travis CI runs on commits and PRs.

2. Squash commits. The project doesn't need a record of you fixing whitespace and spelling mistakes in your PR. As a general rule of thumb, if a commit modifies a previous commit in the same PR, it probably needs to be squashed. That means that a PR may often only be a single commit. This makes rebasing (see below) easier, and keeps the history clean, which can make debugging infinitely easier in the long run.

It's fine to make as many commits as you need while you're working on your local branch. But before your PR is reviewed to be merged, at the latest, it should be rebased. Keeping your history clean as you work will probably be much easier than trying to do it all at the end, though.

If you just want to make a change and have it apply to your last commit, you can use git commit --amend. If you want a change to be associated with an older commit, you can use git commit -i HEAD~3 (where 3 is the number of commits to rebase). You can also use git log to find a commit's hash and git rebase -i <commit hash> (the commit should be the one PRIOR to the commit you want to modify).

Interactive rebase (git rebase -i) will open your default editor in which you can replace pick with fixup or f to combine commits (you can also use this to reorder commits, mark commits to edit their commit messages, and other powerful tools which are explained in the file itself). Save the changes, and git will execute the rebase.

After rebasing, if your branch is already pushed up to GitHub, you'll have to force push the changes using git push -f, since the history has changed.

WARNING: Only rebase your own branches.

3. Use a good commit message

4. Rebase to master. When a PR is merged to master, any active branches will be out of date and not ready to merge. Do not merge master into your branch. Instead, make sure your master branch is up to date:

git checkout master
git pull

Then rebase your branch on master:

git checkout _my-branch_
git rebase master

If there are any conflicts you need to resolve, it will suspend the rebase for you to fix them. Then do:

git add .
git rebase --continue

It will do one round of conflict-checking for each commit in your branch, so keeping your history clean will make rebasing much easier. When the rebase is done, your branch will be up to date with master and ready to issue a PR if you are.