To develop IGB, we use the Forking Workflow described in https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow, but with one difference - we issue pull requests to the development branch, not the master branch.
The following sections describe how to use this workflow to develop IGB.
To contribute a change to the IGB code base, create your own fork of the IGB repository.
To create your own fork:
Next, you'll see a form that let's you give your fork a name and description. Here's an example:
Fill in the fields and click Fork repository.
After a moment, the Overview page for your forked repository will appear. Click Settings and change the main branch to the IGB development branch.
See Atlassian documentation Forking a Repository.
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, use git clone with the address of your remote fork. (Copy the address from your fork's Overview page at Bitbucket.)
For example, if your fork is named my-igb-fork, you would execute
git clone <ADDRESS> |
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 home page on Bitbucket.
If you wish to use a GUI interface for cloning your fork instead of the command line, we recommend using SourceTree, a free Git & Mercurial client available on Windows or Mac.
To clone your fork using SourceTree, download and run SourceTree and then select the Clone/New button near the top of the program.
In the Clone/Add/Create Repository window enter the URL of your fork in the Source Path/URL textbox. Enter your destination path in the Destination Path textbox and then click the Clone button to clone your fork on your local computer.
Before you start making changes to your local clone, you should first create a new branch for the changes you intend to make. This will allow you to issue focused, low risk pull requests that can be easily merged with other branches of development.
To make a branch:
git checkout igb_8_3 |
git branch -b <BRANCH> |
where BRANCH is the name of the branch, e.g., IGBF-203, the name of a story in the IGB JIRA issue-tracking system.
Now, all commits will be associated with the branch you've just created. Commit your changes to your local repo and then push them to your fork hosted on bitbucket.
To make a branch using SourceTree, select the Checkout button near the top of the program to open the Checkout window. From here, select the Checkout New Branch tab and use the Checkout remote branch drop-down menu to select the remote branch you wish to checkout. If you wish to checkout the branch for IGB 8.5.0 you would select origin/igb_8_5. It may be helpful to enter a name for the branch in the New local branch name textbox to indicate the purpose of the branch. Click OK to checkout the new branch.
You can now see all your branches. The current branch is indicated with bold font and a check mark.
You can also pull changes made by other developers from their forks by adding multiple remotes.
To do this using SourceTree, select Add Remote... under the Repository menu to open the Repository Settings window. From here, click the Add button to add a new remote repository. Enter a name for the remote repository being added and enter the URL/ Path for the remote. Confirm that you want to add the remote repository by clicking OK. Your remote repository can be seen under the list of remotes in SourceTree's main window.
Once the remote repository has been added you need to fetch to get the content from the repository. To fetch, select Fetch from the Repository menu. After fetching, you can check out any branch from the remote repository.
To request that your edits be incorporated into the main line of development:
A Pull request form will appear. Fill in the fields:
Bitbucket has utilities to help you pull in the latest code when you are working in their web application (see https://blog.bitbucket.org/2013/02/04/syncing-and-merging-come-to-bitbucket/). However, you will likely want to use the command line to keep your branch in sync with the remote branch you are tracking. The details about how this works are outside the scope of this article; however, we provide a simple example for your reference.
The following example assumes we followed the workflow above and are working on a development branch named igb_8_3.
To bring our remote fork up to date:
git remote add upstream git@bitbucket.org:lorainelab/integrated-genome-browser.git |
Fetch and merge changes from upstream for the development branch named igb_8_3.
git pull upstream igb_8_3 |
git pull --rebase upstream igb_8_3 |
git push origin igb_8_3 |