Contributor Workflow with Github

If you’re a developer who wants to work on the Inception source code and submit your changes for consideration to be merged into the master branch, here’s how.

Quickfire Do’s and Don’t’s

If you aren’t familiar with git and GitHub, try reading the GitHub bootcamp documentation. If you’re familiar with git and GitHub, here’s the short version of what you need to know. Once you fork and download the Inception code:

• Don’t develop on the master branch. Always create a development branch specific to the issue you’re working on. Name it by issue # and description. For example, if you’re working on Issue #100, a XXX bugfix, your development branch should be called 100-XXX-bugfix. If you decide to work on another issue mid-stream, create a new branch for that issue—don’t work on both in one branch.

• Do not merge the upstream master with your development branch; rebase your branch on top of the upstream master.

• A single development branch should represent changes related to a single issue. If you decide to work on another issue, create another branch.

• Squash your commits. After you rebase your work on top of the upstream master, you can squash multiple commits into one. Say, for instance, you’ve got three commits in related to Issue #100. Squash all three into one with the message “Issue #100 Description of the issue here.” Gina won’t accept pull requests for multiple commits related to a single issue; it’s up to you to squash and clean your commit tree. (Remember, if you squash commits you’ve already pushed to GitHub, you won’t be able to push that same branch again. Create a new local branch, squash, and push the new squashed branch.)

• Keep .gitignore clean. Don’t add test files to .gitignore that are specific to your Inception setup. Only working config files, dot files, compiled view files, cache files, and logs should be listed in .gitignore.

Step-by-step

1. Fork on GitHub (click Fork button)
2. Clone to your server ($ git clone git@github.com:you/inception.git)
3. Set up remote upstream ($ git remote add upstream git://github.com/carmaa/inception.git)
4. Branch for new issue ($ git branch ###-description; git checkout ###-description) and develop on issue branch. Use issue numbers from the Issues page.
5. As time passes, the upstream Inception repository accumulates new commits. Keep your working copy’s master branch and issue branch up to date by periodically rebasing: fetch upstream, rebase master, rebase issue branch ($ git fetch upstream; git checkout master; git rebase upstream/master; git checkout ###-description; git rebase master)
6. When development is complete, rebase one more time, then branch from dev branch to release candidate branch ($ git checkout ###-description; git branch ###-description-rc; git checkout ###-description-rc). Squash all X commits that pertain to the issue into one clean, descriptive commit ($ git rebase -i HEAD~X)
7. Push release candidate branch to GitHub ($ git push origin ###-description-rc)
8. Issue pull request on GitHub (Click Pull Request button)

Useful links

• More info on rebasing at the git man page here:
  Git rebase: man page