Github workflow and contribution guide

Overview

This page should allow users that are new to Git to get started with Key4hep software, and describes the workflow for accessing and contributing 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

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.

{% callout “Generate and set up ssh keys for github” %}

If you only want to use the software it may be easier to use https. In that case you don’t need to generate the keys but have to replace git@github: with https://github.com/ in all the instructions. Note that you’ll not be able to push to your repository when you are on lxplus. You can also start using https for now and later re-add your repository with ssh authentication, see the trouble shooting section.

{% endcallout %}

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

For any key4hep repository (taking k4SimDelphes as an example), you will be using (at least) 3 sources:

The official Key4hep repository on github
Your fork of the repository (see github help on what that means)
Your local repository 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]/k4SimDelphes.git # create a local copy (3) of your fork (2)
cd k4SimDelphes
git remote add upstream git@github.com:key4hep/k4SimDelphes.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 --all --prune
```
rebase your development area to the master branch from the official repository (1), please read this to avoid loss of work
```
git rebase -i upstream/main
```
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 repository.

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 a key4hep repository 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 upstream # get changes from the official repo
git rebase -i upstream/main # 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:

upstream git@github.com:key4hep/k4SimDelphes.git (fetch)
upstream git@github.com:key4hep/k4SimDelphes.git (push)
origin	git@github.com:[your git user name]/k4SimDelphes.git (fetch)
origin	git@github.com:[your git user name]/k4SimDelphes.git (push)

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

If you only see origin git@github.com:key4hep/k4SimDelphes.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]/k4SimDelphes.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 key4hep-sw at CERN, and we’ll be happy to help you. Alternatively create an issue in the bug tracker smile .