Github workflow and contribution guide

Page contributors

Joschka Lingemann, Valentin Volkl, Juraj Smiesko

Overview¶

This page should allow users that are new to Git to get started with the FCC software, and describes the workflow for accessing and contributing FCC code.

For a general introduction to git, have a look at these tutorials:

First time setup of git¶

Please refer to this tutorial and the GitHub help.

Generate and set up ssh keys for github¶

When working on lxplus we recommend to clone github repositories via SSH, especially if you want to contribute code. For this to work, you need to generate ssh keys for authentication. See the corresponding github help-page.

Improving your git experience¶

It may be useful to install Git integration tools for your shell that allow tab-completion of most git commands and also can show you in your prompt on which branch you currently are, what changes you have pending, etc.

Development workflow¶

You will be using (at least) 3 versions of the FCCSW repository:

The official FCCSW on github
Your fork of FCCSW on github (see github help on what that means)
Your local repository copy in your work area (e.g. on AFS)

The repositories 1 and 2 are added as remote to the repository 3:

git clone git@github.com:[YOUR_GITHUB_USER]/FCCSW.git # create a local copy (3) of your fork (2)
cd FCCSW
git remote add hep-fcc git@github.com:HEP-FCC/FCCSW.git # add official repo (1) as additional remote

Keeping your local repository up to date¶

fetch all changes from the official repository (1)
```
git fetch hep-fcc
```
rebase your development area to the master branch from the official repository (1), please read this to avoid loss of work
```
git rebase -i hep-fcc/master
```
in this process you can also fix any commits that need touching up, be aware that deleting commits in the list will result also in the deletion of the corresponding changes (more info in the GitHub help and the Atlassian tutorial)
push your local changes to your fork (2), see below how to create a local branch
```
git push origin [NAME_OF_LOCAL_BRANCH]
```

Contributing code¶

if you are fixing a bug, first create an issue in the github issue tracker
develop your feature in your local copy (3) on a local branch of your choice, to create a branch do:
```
git branch -b [NAME_OF_LOCAL_BRANCH]
```
refer to this tutorial to see how to commit changes
occasionally, get new code from the official repository (1) as explained above and merge it in this branch
test:
- that the code compiles and all tests succeed (make && make test)
- that your code runs (even better: add an automatic test)
- that it produces the expected results
push your local branch to your fork (2) (see above)
create a pull request from your fork (2) to the offical repository’s (1) master branch (see github help-page)
- also see the recommendations for pull requests

Recommendations¶

Please always follow the recommendations below.

General recommendations¶

if you’re working on a given topic, always create a branch for it, e.g. pythia_interface. You may commit many times to this branch in your local repository. When you have something solid create a pull request to the official FCCSW repository.
Have a look at our coding guidelines.

Commit comments¶

feel free to commit often to your local repository, make a pull request once the topic you are working on is finished
- if the feature you are working on is large, consider making a work in progress-pull request (see below)
- git commits represent a snapshot of the software as a whole, and not only the difference to a previous commit (although that as well, in practice). It is recommended that each commit compiles and passes the tests. Take a look at the commit history of FCCSW and the histories of some individual files to find both good and bad examples.
always provide a meaningful comment for each commit
- if you are working on an issue, refer to that issue by adding “refs. #[issue id]”, see also GitHub help

commit comments should look like the one below, so that they show up correctly in git printouts.

first version of a pythia interface # this line should be a short 1 liner

Here, you may write a few more lines if needed

Cleaning history¶

before opening a pull request it may be a good idea to check that your history makes sense (commit messages explain what you did, no unnecessary commits, etc.), check with:
```
git log
```
if you see commits that you’d like to change, there are several ways of doing that, the most commonly used is git rebase:
- with the interactive version you can rebase your development branch to the official master and fix the history at the same time
```
git fetch hep-fcc # get changes from the official repo
git rebase -i hep-fcc/master # do the actual rebase
```
- git will guide you through the steps, where you can delete entire commits (and the corresponding changes), merge commits and change commit messages
- more information can be found in this tutorial

Pull requests¶

Give a meaningful title that appropriately describes what you did (e.g. Add new calorimeter clustering)
- Pull requests of work in progress (to make people aware that you are working on a feature) create a PR starting with “[WIP]”
In the description, give a short bullet-point list of what was done
If your pull request fixes issues tracked in the issue tracker:
- Make sure you added a test that shows they are actually fixed
- In the description mention that you fixed it by referring to the issue: “fixes #” (this will automatically close the issue, see also GitHub help)

Trouble-shooting¶

When I try to push to the repository, I get an authentication error¶

Check with git remote -v which remote repositories you have added to your local copy. You should see something like:

hep-fcc	git@github.com:HEP-FCC/FCCSW.git (fetch)
hep-fcc	git@github.com:HEP-FCC/FCCSW.git (push)
origin	git@github.com:[your git user name]/FCCSW.git (fetch)
origin	git@github.com:[your git user name]/FCCSW.git (push)

If you see something similar but all the addresses start with https, see below.

If you only see origin git@github.com:HEP-FCC/FCCSW.git, you need to add your own repository, push to that one and do a pull request, as described above. To add your own repository do:

git remote rename origin hep-fcc
git remote add myfccsw git@github.com:[your git user name]/FCCSW.git

I have cloned with https and now I can’t push my changes, what do I do?¶

You only need to change the URL of your remote pointing to your repository to one that uses SSH instead:

git remote set-url [the remote name] git@github.com:[your git user name]/FCCSW.git

Now you can push to that remote with:

git push [the remote name] [the branch you want to push]

Need help?¶

In case you have any questions on this guide, or need help to sort out an issue with a repository, feel free to drop a mail to fcc-experiments-sw-dev at CERN, and we’ll be happy to help you. Alternatively create an issue in the bug tracker smile