Workflow for contributing to GitHub projects

Lately I’ve been contributing to some open source projects hosted on github. I’m pretty new to git, and the process is a bit confusing for beginners. So, here’s a sample workflow, based on the The Foreman‘s foreman github repository. Note that I’m developing against the “develop” branch of that repository, not the master, so that throws in a little difference that isn’t documented in most introductions. To throw in another wrench, I maintan a branch with the code that I’m currently actually using (i.e. the application code that I have checked out on the production server), called “jantman”. This is more or less composed of the upstream “develop” branch, with all of my finished (but not yet merged in the upstream) topic branches. I’m pretty sure all this is correct, but honestly, I’m still new enough at git that I can’t make any promises. Unfortunatelty, I haven’t had the time to really learn git, and I also can’t find a simple enough tutorial that covers all this…

Fork the original repository through the GitHub interface.

On your machine, clone your fork:

git clone git@github.com:username/reponame.git && cd reponame

Make sure you’ve setup

git config --global branch.autosetupmerge true

Add your upstream repo:

git remote add upstream git://github.com/upstream_user/upstream_repo.git

Fetch it and initialize any submodules:

git fetch upstream && git submodule update --init

Check the current branch (git branch, let’s assume it’s called “develop”) and rebase to its upstream:
```
git rebase upstream/develop develop
```
Create my “jantman” branch, which will be the upstream “develop”, plus my finished work merged into it:
```
git checkout -b jantman origin/develop
```
Create a topic branch to do some work:
```
git checkout -b NewBranchName jantman
```
Periodically, push the topic branch to github:
```
git push origin NewBranchName
```
If you commit to this branch from another computer (or someone else commits to it), periodically update your local tracking branch:
```
git pull origin NewBranchName
```
Periodically, you want to pull in the upstream changes:
1. switch to the develop branch:
```
git checkout develop
```
2. grab the latest version of the upstream git repo:
```
git fetch upstream
```
3. rebase develop to mirror the upstream develop branch:
```
git rebase upstream/develop develop
```
4. switch to our personal branch:
```
git checkout jantman
```
5. rebase our personal branch onto develop (pull all the new commits from develop into our personal branch):
```
git rebase develop jantman
```
6. If we want those new upstream changes to continue down to our topic branches:
```
git rebase develop topicBranchName
```
When we’re done with a topic branch, we want to merge it into our “personal” branch:
```
    git checkout jantman; git merge --squash node-table-facts
```
and then commit:
```
    git commit
```
The --squash will squash all the history of that branch down to one commit. This is generally easier for integration into upstream, and assuming the topic branch was created for a single feature or bug, should be logical.
If we’re sure we don’t need it anymore, delete the topic branch from our local machine:
```
git branch -d topicBranchName
```
and from github:
```
git push origin --delete topicBranchName
```
Finally, make sure we push our “personal” branch back to origin:
```
git push origin jantman
```
Assuming all went well, you’ll see the new commit on github, and have a nice pull request button.

References:

Comments