Git Workflow¶

Git Branching Model¶

For simplicity, we use GitHub Flow, which will be summarized here.

GitHub Flow¶

Anything in the master branch is deployable
To work on something new, create a descriptively named branch off the master (ie: feature/handle-frame-drops)
Commit to that branch locally and regularly push your work to the same named branch on the server
When you need feedback or help, or you think the branch is ready for mergin, open a pull request
After someone else has reviewed and signed off on the feature, you can merge it into master
Once it is merged and pushed to master, you can and should deploy immediately

`Master` branch¶

The origin/master is the main branch where the code of HEAD always reflects a demo-ready state. We treat the master branch as read-only, such that no code should be directly committed to it. Instead, the master branch moves forward only by merging from topic branches.

Topic branches¶

The topic branches always have a limited life time, since they will be removed eventually. Try to keep the commits in a single branch tightly related, and give it a descriptive name.

We recommend using the following prefixes in branch names:

feature/ - New features.
fix/ - Bug fixes.
refactor/ - Code movement or restructuring.

Pull requests and code review¶

We follow the shared repository model. You do not need to fork the repository. Simply use topic branches to sandbox new work. Use the following workflow for development:

Create a topic branch off of master for new work:
```
$ git checkout -b fix/handle-frame-drops
```
Develop your code inside the branch. Commit liberally to track your changes.
Regularly push your branch to the server (origin):
```
$ git push origin fix/handle-frame-drops
```
When you are ready for a code review, or simply want some feedback, initiate a pull request. Go to the repository that you are working on on Github, switch to your branch, and click the Pull Request button.
Github defaults to merging into master. You can click the Edit button and change the merge target to some-other-branch.
Get someone else to review your changes. Revise & iterate until convergence.
Merge your branch. You can merge directly through Github by clicking the Merge pull request button.

To merge locally:

# Checkout the changes if you don't already have the branch locally
git fetch origin
git checkout fix/handle-frame-drops

# Make sure the branch is up-to-date and resolve any conflicts
git merge master

# Fast-forward master, and update the server
git checkout master
git merge fix/handle-frame-drops
git push origin master

Optionally, tidy up defunct branches you do not intend to develop anymore.

Delete local topic branch:
git branch -d fix/handle-frame-drops
If you are dealing with pull request on Github, it will prompt you whether to delete the branch or not after merging. Otherwise, you can do this to clean up the remote topic branch:
# assume remote branch not deleted by Github
git push origin --delete fix/handle-frame-drops
git remote prune origin