To develop IGB and the IGB API, the core IGB development team uses the Fork-and-Branch Workflow described in https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow
Quick Summary: Developers fork the team repository on Bitbucket. When working on a bug fix or new feature, they create a topic branch specific to that task. They push their branch to their fork for review and testing. When all is done, they submit a pull request from the topic branch on their fork to the master branch on the team repository. When working on a task recorded in the IGB JIRA system, they include the corresponding JIRA number (e.g., IGBF-1234) in the branch name and every commit to that branch.
git remote add upstream email@example.com:lorainelab/integrated-genome-browser.git
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.
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 the JIRA and Bitbucket sites to create links to each other.
git checkout -b IGBF-1234
where IGBF-1234 is the name of the new branch.
Edit your code, test it, commit your edits 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.
git commit -m "IGBF-1234 Fix typo - covfefe not collusion"
If the main development branch changes, you must obtain those changes and test them with your branch.
First step is to update your fork's copy the master branch. The easiest way to do this is to use the Bitbucket interface.
To synchronize your fork using the Bitbucket interface:
If all goes well, your fork will then receive all the commits present on the master branch on the team repository. To check that it worked, just review the commit history on your fork and compare it to the team repository.
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.
git checkout master git pull upstream master git push origin master
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.
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 IGBF-1234 git rebase master
Next, push your newly rebased branch to "origin" (your fork) to update it:
git push origin IGBF-1234
To request that your edits be incorporated into the team repository, you need to make a pull request (PR).
To make a PR using the Bitbucket UI:
Things you need to know about PRs:
When you build IGB, existing jar files in the repositories bundle directory are allowed to persist.
This may effect any code changes you may be trying to test.
To be sure that the IGB build you are running reflects the code you currently have, clear all jar files in the bundles directory before building.
The IGB team highly recommends working through the tutorials in Learning Git Branching - https://learngitbranching.js.org/?locale=en_US. Also, when you rebase for the first (or second or third) time, it's helpful to repeat the tutorial on rebasing. Don't worry. You will get the hang of it.