Contributing - FCC Tutorials

FCC Software tutorials, as well as the whole Key4hep ecosystem, is an open source project, and we welcome contributions of all kinds:

New lessons;
Fixes to existing material;
Bug reports; and
Reviews of proposed changes.

By contributing, you are agreeing that we may redistribute your work under these licenses. You also agree to abide by our contributor code of conduct.

Getting Started¶

We use the fork and pull model to manage changes. GitHub also provides more information about forking a repository and making a Pull Request on their website.
For our lessons, you should branch from and submit pull requests against the main branch.
When editing lesson pages, you need to only commit changes to the Markdown source files.
To build the tutorials please follow the instructions.
If you’re looking for things to work on, please see the list of issues for this repository. Comments on issues and reviews of pull requests are equally welcome.

Building the tutorials¶

Requirements¶

Make sure you have venv (virtual environment) in your working directory. It can be created with the following command:

python3 -m venv venv

Activate it in your shell and install the requirements, which are gathered in a file provided by the repository.

source venv/bin/activate
pip3 install -r requirements.txt

After sourcing, your shell prompt will be augmented by the (venv) prefix, e.g.

(venv) mylaptop:~/fcc/fcc-tutorials

Building fcc-tutorials in the Key4hep stack

In case you are editing the tutorials using the FCC Software (Key4hep) stack, it is necessary to clear the PYTHONPATH environment variable after sourcing of the stack

source /cvmfs/fcc.cern.ch/sw/latest/setup.sh
unset PYTHONPATH

Using of the FCCSW stack might also be needed in cases when the Python provided by your OS is too old.

Building¶

The pages are built with Jupyter Book 2, which is based on the MyST-MD engine and needs Node.js (version 18 or newer) available in your PATH. The static HTML site is generated with

jupyter book build --html

and lands in the _build/html directory.

Browsing the result¶

The quickest way to preview your changes is the live-reloading development server, which rebuilds the pages every time a Markdown file is saved:

jupyter book start

You should be able to see your local version by opening a web-browser and navigating to the address printed in the terminal (by default http://localhost:3000).

How to Write¶

More information about how to write the tutorials for the FCC Software visit How to write Mardown.