GitWorkflow.md

Code Review Workflow

Start Your Work

Before starting any work, create a new branch off of the base branch your changes will be submitted to.

E.g. if you are working on a bug, your base branch would be main; if you are working on a feature, your base branch would be that feature's branch.

It is good practice to give the branch a name that is relevant to the work being done.

E.g. fix-cli-printing-bug, add-component-of-feature, etc.

1. Switch to the base branch

   git switch main

2. Update the base branch

   git pull

3. Create a new working branch

   git switch -c WORKING_BRANCH

Save Your Work

Feel free to commit and push changes as often as you'd like to save any progress you've made.

As a general rule, try to make your commits as small and logical as possible. Leaving a trail of your thoughts for reviewers to read is the goal.

1. Add and commit changes

   git add FILES
   git commit

2. Push changes to GitHub

   git push origin WORKING_BRANCH

Review Your Code

1. Commit and pushed any changes you want reviewed.

   git add FILES
   git commit
   git push origin WORKING_BRANCH

2. Go to your repository's GitHub page.

3. Create a Pull Request (Make sure to the base branch on your Pull Request is correct!)

4. Add reviewers (GitHub might make reviewer suggestions, add those as well).

5. Wait for comments and requests.

Address Comments

Reviewers will undoubtedly have comments and/or make requests for your changes.

For each request, add a new commit to address that request, then push your new commits.

Every time you push, the Pull Request will be automatically updated and reviewers notified.

Note You do not need to push each commit. Making several commits and pushing once is fine.

Warning Do NOT rebase or amend commits, i.e. no force pushes please.

Merge Your Code

Once you have gotten enough approvals, use the Squash and Merge button to prepare your changes for merge.

Warning Do NOT merge other people's Pull Requests

The Squash and Merge button will present you with a text box to write a merge title and message. Check that the merge title and message match your PR title and message.

Note Try to make your commit message informative and helpful.

General rules for commit messages:

• For bug fixes, explain why this change fixes the bug.
• For feature work, explain how this part of the feature is supposed to work.

If you'd like to read more about writing good commit messages check out this blog post.

Start Over

Now that you're finished, it's time to get back to work!

To start new work, follow the same steps as before:

1. Switch to your base branch

   git switch main

2. Pull the latest changes

   git pull

   Warning If you get a merge conflict or git tries to create a merge commit, see below

3. Create a new branch for your work

   git switch -c NEW_WORKING_BRANCH

Note, you do not need to do anything to your old branches, but if you do want to cleanup old Pull Request branches, checkout this Stack Overflow answer.

Wait, But What If?

Git won't let me pull main

If you are having trouble running git pull on a base branch like main, it may be that you accidentally made a commit on the base branch before creating your working branch.

To fix this, create a tag on your current main branch to make sure no commits are "lost"

git switch main
git tag USERNAME/save-main

Then re-checkout the main branch

git checkout USERNAME/save-main
git branch -D main
git fetch
git switch main

My branch and the base branch have diverged

As long as there are no merge conflicts (which GitHub will warn you about), there is nothing you need to do.

The Squash and Merge button will handle the divergence like magic.

I have merge conflicts!

Use Git's merge command to merge the base branch into your working branch, resolve all conflicts, and push.

git switch main
git pull

git switch WORKING_BRANCH
git merge main

Resolve merge conflicts

git commit

My branch is really out of date

Same as above, use Git's merge command to update your working branch.

git switch main
git pull

git switch WORKING_BRANCH
git merge main

My new work depends on my open Pull Request

In this case, create a branch off of your Pull Request branch and start working from that.

git switch PR_BRANCH
git pull

git switch -c NEW_WORKING_BRANCH

FYI, you can use a Draft Pull Request for work that is not yet ready.

My new work depends on someone else's open Pull Request

This is identical to the solution above, except you'll need to use that user's Pull Request branch before creating your new branch.

git fetch
git switch COWORKERS_PR_BRANCH
git pull

git switch -c NEW_WORKING_BRANCH

Make sure to keep your branch up-to-date with changes from that user's Pull Request by periodically merging their branch into yours.

git pull origin COWORKERS_PR_BRANCH

I'm halfway done, but now I'm stuck waiting for someone else's fix

This is identical to the last step of the solution above. You just pull the other user's Pull Request into an existing branch instead of creating a new one.

git pull origin COWORKERS_PR_BRANCH

Someone else has pushed changes to my Pull Request

Sometimes it makes sense for a reviewer to push changes to your Pull Request. This is fine, but you will need to pull those changes locally before you will be allowed to push any of your changes.

With your working branch checked out, use the pull command with the remote and branch parameters to pull changes from your Pull Request branch.

git switch PR_BRANCH
git pull origin PR_BRANCH

WTF?!?!

Come on over to the #help_git Slack channel and someone will help you out :)

Useful Stuff

• Git documentation
• Git basics
• Git in Bash
• GitHub Enterprise documentation
• GitHub desktop app
• GitHub command line tool