...

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 http://bitbucket.org/lorainelab/integrated-genome-browser (the team repository)
• Select Fork

Next, you'll see a form that let's you give your fork a name and description. Here's an example:

...

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":

git remote add upstream <ADDRESS> 

where ADDRESS is the address of the team repository.

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 new branch is called a "feature branch" and should only contain modifications that implement a 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 feature branch:

git checkout -b BRANCH<BRANCH>

where BRANCH is the name of the new branch, e.g., IGBF-203, the name of a story in the IGB . Branch names always should refer to issues in the JIRA issue-tracking system. In this example, BRANCH is branched - 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.

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:

...

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, merge those changes into your fork early and often. 

To bring your remote fork up-to-date:

...

, fetch and merge changes from the team repository's master branch using  pull commands. Note, 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:

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

checkout master

pull the new commits from master to your local clone:

git pull upstream master

orand push the new commits to your fork:

git pullpush --rebaseorigin upstream master

• Push these changes back to your fork's master branch (aliased to "origin" in this example)

...

master

Recall that "origin" is aliased to your fork on bitbucket.

Rebase your branch

After updating your clone and fork with the latest changes to the master branch, you'll need to merge those new commits with your feature branch. The IGB team recommends you use "rebase" commands to do this. This makes the commit history for the IGB project much cleaner as it will simply move the "base" of your feature branch to the latest commit on the master branch.

See: https://git-scm.com/book/en/v2/Git-Branching-Rebasing

To rebase your branch on the latest master, update the master branch (see above), check out your feature branch, and rebase:

git checkout <BRANCH>
git rebase master

Next, re-push your branch to "origin" (your fork) to update:

git push origin master<BRANCH>

Issue pull request

To request that your edits be incorporated into the team repository - aliased to "upstream" - you need to issue a pull request.

• Go to your fork's project Overview page
• Select Create Pull Request

...

• 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

Note that the team repository already has dozens of branches, most of them leftover from older workflows. DON'T push your branch as an all-new branch to the team repository as this just adds to the clutter!

Other info

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.

...

Building javadocs

To build javadocs, run

mvn javadoc:javadoc