GitHubWorkflow

Introduction

This page describes a recommended git workflow for use with the Mu2e Offline code once we have switched to GitHub.

Downloading Offline as a user and NOT a developer

Option 1: you want the default primary version of the code (most people):

1. clone the repo:
git clone https://github.com/mu2e/Offline
2. Done!

Option 2: A particular collaborator has a version or branch you want to use:

1. Find their github user name
2. Determine what the name of the branch they are working on is (Note: this can be master!)
3. Clone their fork:
git clone https://github.com/<user name>/Offline cd Offline git checkout origin/<branch name>
4. Done!

Option 3: You want to use pgit to avoid a long compilation time (EXPERIMENTAL)

1. Create new directory to put your Offline repo in and move to that directory
mkdir Offline cd Offline
2. As in Option 2, determine fork and branch name you wish to use
3. Create a partial checkout clone
pgit2 setup https://github.com/<user name (or mu2e)>/Offline <branch name>
4. You can now use as normal:
source setup.sh scons -j 4

Developer Workflow

• To start, you will want to make sure you understand what a remote is, and the difference between a branch and a fork
• You will also need a GitHub account, and to make sure you are added to the Mu2e github organization (https://github.com/orgs/Mu2e/people)

1. Before we do any developing, we will create our own fork of the official Mu2e Offline repo using the GitHub web interface (instructions here). This fork will be your personal sandbox on GitHub; you can do anything you want to it and it will have no effect on anyone else!
2. Create a local clone of your Offline fork. This will be identical to cloning the official mu2e repo (if your fork is up to date), except that the default remote (called "origin") where you will push to by default will point to your fork instead of the official mu2e version.
git clone git@github.com:<your user name>/Offline
3. (Not required) To be more descriptive about the change you are working on, you can create a new branch to develop your feature on. Again since we will be pushing to your fork, this has no impact on the main Offline, and the only time the branch name will actually show up otherwise is if you are pointing other people to your changes or in the comment of the final merge commit back into the master branch (or if you are working on several things at once and want to keep them separate).
git checkout -b <new branch name>
4. Do your work and commit it locally
git commit -m "this is my normal commit onto my local branch"
5. If there are changes in the official master branch, you can grab them and merge them in
1. First you need to add the mu2e/Offline repo as a new "remote"
git remote add mu2e https://github.com/mu2e/Offline
2. now you can pull/fetch/merge from that repo (or from any other fork by the same procedure)
git fetch mu2e git merge mu2e/master
6. Push your work to your fork
1. If you are working on the master branch of your fork:
git push origin master
2. If you are working on a different branch, then the first time you push add the "-u" option to tell git that these branches "track" each other (see https://lornajane.net/posts/2014/understanding-tracking-branches-in-git)
git push -u origin <branch name>
7. When you are ready to have your changes propagated back into the main mu2e Offline repo, open a pull request.
1. In a web browser, open https://github.com/<your user name>/Offline
2. If you just pushed, there should automatically be a message about your new changes and a link to automatically open a pull request
3. Otherwise follow the github instructions
8. On the next software call, be prepared to discuss your changes
9. If issues are found with your changes, just commit and push again, the pull request will automatically be updated
10. After a code review, the admins will merge in your branch, and you are done!
11. Cleanup before continuing:
1. if you created a new branch and you are done with this feature completely, go ahead and delete the branch (remember no history is lost as this whole branch is now part of master, including all provenance)
git branch -d <my branch name> git push origin --delete <my branch name> (this deletes the branch from your github fork as well)
2. if you used the master branch on your fork, or you are planning to continue to develop this feature, just make sure to update it to include the merge commit created by the pull request
git fetch mu2e git merge mu2e/master