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

Collaborating on a feature

Sometimes you may want to collaborate on a feature branch with other developers. In this case since the main Offline repository no longer has all the development branches we need to do a couple extra steps

1. First make sure you actually need to work on the same branch. Are you actually working on the same feature? Can the problem be split into smaller features that can be developed asynchronously? Just because features are related doesn't mean they need to be developed on the same branch
2. Determine if a large number of people will be developing on the same branch for a significant amount of time. In this case it should become an official branch in the mu2e/Offline like MDC2018
3. Decide which users fork will be the primary repo for this feature branch, and which branch on that fork you are going to use. If a new branch is needed, the owner of that fork can do as usual:
git clone git@github.com:<their user name>/Offline git checkout -b <new branch name> git push -u origin <new branch name>
4. There are then a couple options for moving forward: either add all other developers as collaborators on the primary fork, or use pull requests to the primary fork
5. To add developers as collaborators:
1. The owner of the primary fork opens https://github.com/<their user name>/Offline
2. click settings on the right, then collaborators
3. In the collaborators box, type the github user name of each other developer and hit "Add collaborator"
4. The other collaborators can then either create a read/write access clone of the primary fork, or add it as a remote to an existing offline repo
git clone git@github.com:<primary user name>/Offline or git remote add primaryfork git@github.com:<primary user name>/Offline
5. The other collaborators can now push directly to the primary fork as if it was their own:
git push primaryfork <branch name>
6. To use pull requests:
1. The owner of the primary fork can just push to it as normal following the normal developer workflow
2. Other developers clone their own fork, but add the primary fork as a remote
git remote add primaryfork git@githbub.com:<primary user name>/Offline
3. Other developers can pull in and merge changes from collaborators by fetching/pulling/merging from this remote
git fetch primaryfork git merge primaryfork/<branch name>
4. Other developers push to their own fork
git push origin <branch namee>
5. Like in the normal developer workflow, they open a pull request. But then in the compare window before creating the request, change the "base repository" from mu2e/Offline to <primary user name>/Offline (see here)
6. the owner of the primary fork will need to accept and merge it in
7. everything else goes like the normal workflow