Git

As per the software programming standards, all CTAO software must be under version control using Git. Git is a distributed version control system, which means that each checkout of a repository has the full history and changes like commits can be made without talking to a central server. However, for almost all software using git and also for the CTAO software, there is a canonical source repository, from which official releases are made and which serves as a basis for the features added to Git by the hosting providers like issue tracking, merge requests etc.

Recommended Reading

Books

• Pro Git, Scott Chacon and Ben Straub, 2nd Edition, Apress Note: this book is continuously updated and the PDF and epub versions are freely available.

Online Resources

• Command line Git

• Learn Git Branching

• Git Lecture at the 2021 Escape School, Maximilian Linhoff. Slides and Video Recording

Recommended Git Workflow

There are many different ways to organize collaboration on code in Git repositories, that differ on how branches are named, when branches are made and merged and from which branches releases (tags) are made.

The recommended workflow for CTAO projects is the so-called feature branch workflow. The main ideas are:

• There is a single branch for the current software, which should be called main

• Changes are developed on feature branches that are merged via merge requests into main

• Before changes are merged, automatic checks run (CI) and code review happens

• Feature branches should be as small and short-lived as possible

Most team members should have direct write access to the repository but the main branch should be protected so that only maintainers can merge changes into it. By working on feature branches in the main repository itself, the overhead of keeping a fork synchronized is avoided, and it is easier to collaborate on a feature branch with other developers in the team.

Only if giving someone write access to the repository is not reasonable (e.g. external contributors, where external can mean CTAO but different team or even external to CTAO), forking is necessary to contribute.

In cases where a project needs to maintain multiple versions of the software with bug-fix releases in parallel, e.g. v1.5.x and v2.0.x, the main branch is used for the newest version. Additional release branches for the older but still maintained version of the software should be created starting from the corresponding release tag, e.g.:

git branch v1.0.x v1.0.0

Starting a new Feature Branch

New feature branches should always start from an up-to-date main branch. To ensure this, always fetch before branching and explicitly give the base branch on the command line:

Working in the main repository

$ git fetch
$ git switch -c <new branch name> origin/main

Working in a fork

$ git fetch upstream
$ git switch -c <new branch name> upstream/main

It is recommended to give meaningful names to branches, for example including the issue number and a very short summary when addressing a bug: bugfix-123_segfault_during_startup.