Table of Contents

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:

...

How this works: When working on a bug fix or new feature, you should create a topic branch specific to that task. When done, submit a pull request from that topic branch to the master branch on the team repository. If working on a task recorded in the IGB JIRA system, always include the corresponding JIRA number (e.g., IGBF-1234) in the branch name and every commit to that branch. Also, before submitting a pull request, rebase your branch onto the latest tip of the master branch. Please rebase instead of merging to help simplify the commit history and make the project easier to maintain. 

...

Step-by-Step Set-up Guide 

Fork the code on Bitbucket - configure your fork

1. Sign up for a free account on Bitbucket using an "edu" address if you have one.
2. Set up ssh for git to avoid having to enter your password every time you interact with Bitbucket using git. See: Set up SSH for Git.
3. Using your Bitbucket account, fork the team repository: https://bitbucket.org/lorainelab/integrated-genome-browser

...

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:

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.

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

...

2. Configure your fork to link to team project management software JIRA. 
   1. Log into Bitbucket 
   2. Go to your fork home page
   3. Select "Settings > Links > Add new link"
      1. Choose Link type "Jira"
      2. Enter Link url https://jira.transvar.org/
      3. Enter Link key IGBF
   4. Check that the links work - select "Commits"
   5. Look for commit messages containing the Link key "IGBF"
   6. Note that all link keys now link out to JIRA

Note: Users with ".edu" accounts get more Bitbucket pipeline build minutes. If you are developing the Core IGB code base, you will need this to build branch-specific installers for testing. 

Clone your fork and add team repository as an upstream

1. Clone a copy of your forked IGB repository onto your computer using your favorite git client software. 
2. Add the team repository as a remote called "upstream" (the convention.)

For example:

git remote add upstream <ADDRESS> 

where ADDRESS is the address of the team repository.

...

git@bitbucket.org:lorainelab/integrated-genome-browser.git

Start work - 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. 

Important: If you are working on a task captured in the IGB JIRA project, include the JIRA issue number in the branch name. This enables JIRA and Bitbcuket to create links to each other.  c

For example:

git checkout -b <BRANCH>IGBF-1234

where BRANCH IGBF-1234 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. If working on a JIRA issue, always include the JIRA ticket name in the commit.

For example:

• Commit a bug fix to your local copy:

git commit -m "IGBF-1234 Fix typo - covfefe not collusion"

• Push to the remote repository, aliased to "origin". (This is a default setting in git.)

git push origin BRANCH

...

"

...

Synchronize early & often with the main repository

...

First step is to update your copies of fork's copy the master branch. Note that this assumes you have already added the team repository as a remote repository named "upstream."The easiest way to do this is to use the Bitbucket interface.

To synchronize your clone and your fork, switch back to the master branch:

git checkout master

pull the new commits from master to your local clone:

git pull upstream master

and push the new commits to your fork:

git push origin master

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. 

fork using the Bitbucket interface:

1. Log in to your Bitbucket account
2. Go to your forks home page
3. Select "Repository Details"
4. Look for the "Sync" button. Click it.

Note: the Sync button appears only if your fork lacks commits present on the team repository's master branch.  By default, Bitbucket shows you the master branch.

You can also update your fork's master branch from the command line. For that, check out your master branch on your clone and pull changes from the master branch from the team repository, aliased to "upstream." Then, push the changes to your fork. 

For example:

git checkout master
git pull upstream master
git push origin master

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, update it with any new commits, check out your feature branch, and rebase. synchronize your fork's master branch with the team repository (see above), check out your feature branch, and rebase.

For example, let's assume you have committed all your work to your topic branch - called IGBF-1234 in this example. Then run:

git checkout master
git pull origin master # assumes your fork is up-to-date
git checkout <BRANCH>IGBF-1234
git rebase master

Push Next, push your newly rebased branch to "origin" (your fork) to update it:

git push origin <BRANCH>

...

IGBF-1234

Make a pull request - PR

To request that your edits be incorporated into the team repository - aliased to "upstream" - , you need to make a pull request (PR). 

To make a PR using the Bitbucket UI:

• Log in to your Bitbucket account.
• 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
• and select "Branches"
• Under "Pull request" select "Create" next to your branch
• A pull request form will appear. Fill in the fields:
  
  • Select your
  branch (see above) as
  • fork and your branch as the pull request source (left side).
  • Select the team repository (lorainelab) and master branch as the pull request target (right side)
  .
  •  
  • Click
  Create pull request
  •  Create pull request

Things you need to know about PRs:

• If you make changes to your branch (the source of the PR), those changes will be reflected in the PR. You do not need to create a new PR if you add new commits or otherwise modify your branch. 
• You should always rebase onto the latest master branch before submitting a PR. 
• The project admins get email notifications whenever someone submits a PR. However, if you do not hear anything about your PR, get in touch.