Skip to content
Snippets Groups Projects
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
After you've reviewed these contribution guidelines, you'll be all set to contribute to this project.

Overview

The Common Analysis Framework (CAF) is the back-end to multiple ATLAS analyses. Most analyses use it to loop over events with calibrated particles (xAODs or ntuples, but other inputs can easily be added), apply a set of cuts and produce cutflows and histograms. This functionality (and much more) can be found in QFramework. The SFramework provides a convenient interface to RooFit via the C++ interface of HistFactory.

Contributing

General

We - the current developer team - try hard to keep the code very general so that a wide range of analyses can benefit. This being said, maintaining this code and developing new features requires some work and we have more ideas for improvements than we have time to implement them. If you are interested in some of them, take a look at our issues, where we keep track of both our good ideas (which sometimes sit around for quite a while) and urgent problems that need immediate attention.

If you want to contribute to CAF (be it because you need a new feature in your analysis, you want to familiarize yourself with the code or you just want to contribute to a cool framework), feel free to get in touch! For all questions, we maintain the mailing list qframework-users@cern.ch.

Working with git

We use git to keep a record of earlier code versions. git also helps with simultaneously collaborating on the same code. If you want to make changes to the code, the standard procedure is to

  • create an issue here (this step is optional, but it can be helpful to specify the general purpose of your changes)
  • create a merge request (MR) here or create it directly from your issue
  • check out the branch that's created at the same time as the MR
  • work on it (general advice: commit early, commit often)
  • push the changes
  • remove the WIP label from your MR and tag someone to review your changes
  • ask someone in the developer team to merge your changes into the master branch This procedure is also summarized in the beginning of the most recent CAF tutorial.

Specifics in CAF

The main branch in our repository is the master branch. It is not allowed to push directly to this branch and it can only be changed with a merge request on gitlab. We also have a cosmetic branch. It can be used for minor issues (documentation, typos and trivial code changes), for which a new branch and MR would be too much effort. This branch is merged into master frequently. And of course, there are many feature branches for specific issues. Don't hesitate to create your own branch!

To visualize the severity and type of an issue, we use gitlab labels. A description of the labels can be found here.

We try to help inexpericend users by tagging certain versions of CAF. These tags have the format YY.MM.V, where YY indicates the year, MM the month and V the version (starting with 0 and counting up in case of updates), while the branch YY.MM.X always points to the latest version. The purpose of tagged versions is to provide versions of the code which have been tested and seem to work reliably.

Every MR should have a description and this description should concisely summarize new features. MR descriptions in CAF have two sections: Release notes and Details. The first one should tell the inexperienced user which new features to expect. The Details section can be a more elaborate version, but is also meant to contain all the nasty information about the implementation that you want to give to experienced CAF people. These two MR sections are separated, because we auto-generate a list of MRs in an effort to document the changes between CAFCore tags. This auto-generated list will contain the text in Release notes, but not the text in Details.