Git Branching

The onboarding document includes some information about our development workflow, but if you're new to git or haven't used GitHub with multiple developers before, it can be difficult to figure out the practicalities of the process. This document explains some best practices to get you started.

If you have not already, work through the Git lab first, then come back to this document later.

When joining a new project

1. On the GitHub project page, click the Fork button near the top right to create your own fork.
2. Once the fork is complete, copy the clone URL for your fork. It's in the project header area, above the file list.
3. On the command line, git clone that copied URL, then cd into the newly-created project directory.
4. Back on GitHub, go back to the original Vokal project page, and copy the clone URL from the project header.
5. On the command line, add the Vokal repo as a remote source: git remote add vokal [copied URL]
6. You now have two remote sources: vokal is the original repo, and origin is your fork.

When working on something new

1. Check out master: git checkout master
2. Create and switch to a new branch: git checkout -b bug_fixes_or_whatever
3. Do your work and commit your changes.

When finished with a feature or bug fix

1. If you have not yet pushed your branch, make sure the branch is fully up to date with changes that other developers have made:

• Update your master branch: git checkout master, then git pull vokal master
• Rebase onto master: git checkout bug_fixes_or_whatever, then git rebase master

2. If you have pushed your branch, you should not rebase it, because doing so will require a push --force to overwrite the branch that's on GitHub; this is generally frowned upon, since it will really screw things up if someone else has checked out that branch. Instead, create a new one and rebase that:

• Update your master branch: git checkout master, then git pull vokal master
• Create a new branch from your working branch: git checkout bug_fixes_or_whatever, then git checkout -b rebased_bug_fixes_or_whatever
• Now, rebase that new branch onto master: git rebase master
• For the remaining steps, use your new branch, which we called rebased_bug_fixes_or_whatever in this example.

3. Push your branch to your fork of the repo: git push -u origin bug_fixes_or_whatever (include the -u so you don't need to specify the branch name next time you push)
4. On GitHub, open the project page, in your fork or the original Vokal project.
5. You'll see a big green button at the top offering to create a new pull request. Click that to start a pull request and review the changes you've made.
6. Before or after opening the PR, you can commit more changes and git push them to add them to the PR.

While the PR is in review: if you want to continue working

1. Create a new branch from your previous one: git checkout -b more_fixes
2. Do NOT push this branch yet. You'll do that later, after the previous PR has been merged.

While the PR is in review: if you need to make changes based on code review feedback

1. Make sure you have the branch for that PR checked out: git checkout bug_fixes_or_whatever
2. Make your changes and commit them
3. Push them to your fork: git push

Once a PR has been merged

1. Update your local master branch: git checkout master, then git pull vokal master to get the latest commits from the master branch in the Vokal project.
2. Push the updates to master to your fork: git push origin master
3. Delete your local branch that has been merged: git branch -d bug_fixes_or_whatever. This step isn't strictly required, but you'll quickly find yourself overwhelmed with old branches if you don't keep them tidy.

If you had changes in another new branch while waiting for code review

1. Checkout your other branch: git checkout more_fixes
2. Since that branch was forked from your previous feature branch, you need to rebase it onto master so that your new commits are tacked on after the merge commit: git rebase master
3. Now, you can push your new branch: git push -u origin more_fixes