To develop IGB and the IGB API, the core IGB development team uses the Forking Workflow 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 repository.
To create your own fork:
- Sign up for Bitbucket account
- Go to http://bitbucket.org/lorainelab/integrated-genome-browser
- Select 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, an Overview page for your forked repository will appear.
Also see Atlassian documentation Forking a Repository.
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:
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 Overview page on Bitbucket.
Make a branch
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 are easy to merge with other developers' work.
To make a branch:
git checkout -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. In this example, BRANCH is branched from the master branch, the main line of development for IGB.
Edit code, 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:
git commit -m "Correcting a typo - joe instead of jeo"
- Push to the remote repository, aliased to "origin"
git push origin BRANCH
Note that "origin" is aliased to your fork on Bitbucket, not the team repository.
Synchronize with the main repository
If the main development branch changes, you merge those changes into your fork early and often.
To bring your remote fork up-to-date:
- Add the original, main IGB repository as a remote git repo with the alias "upstream"
git remote add upstream git@bitbucket.org:lorainelab/integrated-genome-browser.git
Fetch and merge changes from upstream's master branch using pull or rebase commands
git pull upstream master
or
git pull --rebase upstream master
- Push these changes back to your fork's master branch (aliased to "origin" in this example)
git push origin master
Issue pull request
To request that your edits be incorporated into the team repository - aliased to "upstream".
- Go to your fork's project Overview page
- 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).
- Fill in the Title and Description fields
- Click Create pull request
GenoViz Software Development Kit
IGB uses graphical user interface components in the GenoViz Software Development Kit. Normally, when you build IGB, you'll use a copy of the GenoViz SDK downloaded from our maven repository at http://eos.transvar.org/nexus/. However, if you clone and build your own copy, your version will automatically get added to your local maven repository.
Build the javadocs
To build javadocs, run
mvn javadoc:javadoc