...

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

...

1. Sign up for a free account on Bitbucket. Use an "edu" address if you have one to get more "build minutes" with Bitbucket pipelines. 
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
4. 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.transvarbioviz.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

Install Git

1. Windows users: Git for Windows

Clone your fork and add the team repository as "upstream"

...

where IGBF-1234 is the name of the new branch.

To test your set-up, trying compiling and running IGB.

To build and run IGB from the command line:

1. Install Apache maven (these directions from the Baeldung site are helpful)
2. Change into the project directory and type mvn install
3. Start IGB by running one of the "run_igb" scripts in the top level of the project.

Note: Following the upgrade of IGB to Java 21, it may not be possible to run IGB from within an IDE. This is due to the requirement to expose internal Java modules. You should be able to build IGB from within the IDE, but to run it please use one of the "run_igb" scripts from your terminal.

Edit code, commit to your clone, push to your fork

...

If the main development branch changes, you must obtain those changes and test them with your branch.

First step is to To update your fork's copy of the master branch. The easiest way to do this is to use the Bitbucket interface.

To synchronize your fork using the Bitbucket interface:

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

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 main branch, check out your main branch on your clone and pull changes from the master main branch from the team repository, aliased to "upstream." Then, push the changes to your fork. 

For example:

git checkout mastermain
git pull upstream mastermain
git push origin mastermain

If all goes well, your fork will then receive all the commits present on the main 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. 

Rebase your branch

After updating your clone and fork with the latest changes to the master main 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 main branch. 

To rebase your branch on the latest mastermain, switch back to the master main 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 mastermain
git pull origin mastermain # assumes your fork is up-to-date
git checkout IGBF-1234
git rebase mastermain

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

git push origin IGBF-1234

Squash commits

If you have made multiple commits for a single Jira ticket it is usually best to squash the commits into a single commit before creating a pull request. See the Git cheat sheet for more information.

Make a pull request - PR

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

...

• Log in to your Bitbucket account.
• Go to your fork and select "Branches"
• Under "Pull request" select "Create" next to your branch
• A form will appear. Fill in the fields:
  
  • Select your fork and your branch as the pull request source (left side).
  • Select the team repository (lorainelab) and master branch main branch as the pull request target (right side) 
  • Click Create pull request

...

• 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 main branch before submitting a PR. 
• Please squash all your commits into one single commit, unless you have a very good reason not to. This ensures that we can easily apply your changes to other branches if required. It also makes code review easier. 
• The project admins get email notifications whenever someone submits a PR. However, if you do not hear anything about your PR, get in touch.  

...