To develop IGB and the IGB API, the core IGB development team uses the Forking and Feature Branch Workflows described in https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow
The following sections describe how to use this workflow to modify IGB. This assumes you understand the basics of how to use git.
Fork the code on Bitbucket
To contribute a change to the IGB code base, create your own fork of the IGB team repository.
To create your own fork:
- Sign up for Bitbucket account
- Go to https://bitbucket.org/lorainelab/integrated-genome-browser (the team repository)
- Create a fork (top left)
Tip: Sign up using an academic .edu address to gain access to more features.
Clone your fork
Clone a copy of your forked IGB repository onto your computer. You will make changes to your local clone, commit them to your local repository, and then ultimately push your changes to your fork hosted on Bitbucket.
To clone your fork:
where ADDRESS is the address of your fork on Bitbucket. To get the address of your fork, look at the top the top right of your fork's Overview page on Bitbucket.
To avoid having to enter your password each time you interact with your fork on BitBucket, set up ssh for git. See: Set up SSH for Git.
Add "upstream" - an alias to the team repository
Use git to add the team repository as a new remote repository to your local clone. By convention, the team repository (which you forked) should be named "upstream".
To add the team repository as a remote called "upstream":
where ADDRESS is the address of the team repository.
Make a branch
Before you start work on a new feature, bug fix, or other improvement, create a new branch for the changes you intend to make. This new branch is called a "topic branch" and should only address one specific, discrete feature or bug fix. This is critical! Doing this will allow you to issue focused, low risk pull requests that are easy to merge with other developers' work.
To make a new topic branch:
where BRANCH is the name of the new branch. Branch names always should refer to issues in the JIRA issue-tracking system - for example: IGBF-203. Branches should always derive from the master branch, the main line of development for IGB. To ensure this happens, make sure you are "on" the master branch before creating a new branch.
Note: Topic branches are sometimes also called "feature branches." However, this is may not be the best name because often branches deal with bug fixes or improvements to existing features. The term "topic branch" is a better name because it covers more options.
Edit code, commit to your clone, push to your fork
Edit your code, test it locally, commit your changes to your local copy, and then push them to your fork hosted on Bitbucket. For example:
- Commit a bug fix to your local copy:
- Push to the remote repository, aliased to "origin". (This is a default setting in git.)
Note that "origin" is aliased to your fork on Bitbucket, not the team repository.
Synchronize early & often with the main repository
If the main development branch changes, you must obtain those changes and test them with your branch.
First step is to update your copies of the master branch. Note that this assumes you have already added the team repository as a remote repository named "upstream."
To synchronize your clone and your fork, switch back to the master branch:
pull the new commits from master to your local clone:
and push the new commits to your fork:
Recall that "origin" is aliased to your fork on bitbucket.
Now the master branch is up-to-date on your clone and fork.
Note: You can also use the Bitbucket Web site to do this. Visit your fork's Web site and use the right-side menu to synchronize your fork.
Rebase your branch
After updating your clone and fork with the latest changes to the master branch, you'll need to test how those new commits interact with your topic branch. You should use "rebase" commands to do this. This will move the "base" of your topic branch to the latest commit on the master branch.
To rebase your branch on the latest master, switch back to the master branch, synchronize your fork's master branch with the team repository (see above), check out your feature branch, and rebase:
Push your newly rebased branch to "origin" (your fork) to update it:
Issue pull request
To request that your edits be incorporated into the team repository - aliased to "upstream" - you need to make a pull request.
- Go to your fork's project Overview page and click the branches link
- Go to the branch you want to merge
- Select Create Pull Request
A pull request form will appear. Fill in the fields:
- Select your branch (see above) as the pull request source (left side).
- Select the master branch as the pull request target (right side).
- Click Create pull request