Skip to end of metadata
Go to start of metadata

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:

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:

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 IGB project prefers the term "topic branch" because it is more general.

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"

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.

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. The IGB team recommends you 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, update the master branch (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 issue a pull request.

  • 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

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. And DON'T merge your branch with master.

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

  • No labels