Contributing to the repository

In order to start contributing to the O2Physics code you first have to fork the O2Physics repository on GitHub and add the URL of your fork as the origin remote repository in your local Git repository.

In order to contribute new code to the central repository, please follow these steps:

• If you are adding a new workflow:
  • Place your cxx file in the appropriate directory (see the O2Physics repository structure).
  • Add the workflow compilation instructions in the CMakeLists.txt (you can clone one of the existing o2physics_add_dpl_workflow blocks). Follow the kebab-case naming convention of the executables (i.e. lowercase words separated by hyphens).
• Compile O2Physics with your changes.
  • Make sure the compilation of your code does not produce any errors or warnings.
  • In case you added a new workflow, the newly created executable will have the name you specified on the o2physics_add_dpl_workflow line, prefixed with o2-analysis-<xx>-, where <xx> corresponds to the PWG<XX> folder your file is in.
• Test your code.
• Commit your changes and push them to your remote fork repository on GitHub.
• Create a pull request (PR) from your fork repository to the main repository.

See also the comprehensive guide through the GitHub flow for a more detailed overview of the contribution steps.

Pull requests

Each PR is tested for formatting, coding and compilation issues and needs to be reviewed and approved by the code owners before it can be merged.

If your changes are not ready for review or merging yet but you still want to create a PR, please use the option "Create draft pull request" which will not notify the code owners nor trigger the compilation checks. A draft pull request can later be turned into a normal PR using the "Ready for review" button.

Keep pull requests small and focused.

• Create one PR per feature, i.e. do not mix big unrelated code changes (e.g. add a new workflow file and add histograms in another workflow).
• Keep in mind that the larger a PR is, the longer it takes to review it, especially when a new workflow is being added.

Give your pull request a short and meaningful title.

• The title should be informative enough to give an idea of what was changed and where.
• Further details (e.g. why this change is needed or related links) can be provided in the description below the title.
• It is useful to put the PWG name at the beginning of the PR title to specify the scope of the changes, which makes it easier to filter PRs related to the PWG in the PR history and also in the commit history of the main branch.
• Examples of too vague titles: "Test", "Fix bug", "Add new parameter", "Update cuts", "Improve code".

Automatic checks

Pull requests are tested with automatic checks which get restarted whenever the commits in the PR change. The compilation checks ("build/…") run only on PRs marked as ready for review (i.e. not on draft PRs). PRs from first-time contributors (who have not authored any commit in the repository yet) require an approval to start the compilation checks.

If a check fails, you can click on "Details" to see more information about the errors in the log of the test.

If the clang-format check (or a formatting linter in MegaLinter) fails, an automatic PR with the formatting fixes is opened in your fork and a notification email is sent to you. You have to merge this formatting PR to update your branch (and your opened PR).

Pull request review

The approvers (code owners) are listed in the CODEOWNERS file and are notified automatically by email when you open a PR for review. If your PR touches several files with different groups of code owners, you need an approval from each group.

When you implement changes during the review, push them into your branch as additional separate commits with meaningful titles, on top of the existing commits.

• Do not amend, squash or rebase existing commits in the PR (unless asked to do so by the code owners)! You would have to force the push to update your branch which would overwrite the commit history, break the links between the code and the review comments and make the PR review more messy.
  • If you need to update your branch with the changes in the main branch while the PR is under review, use git merge upstream/master (instead of rebasing) to preserve the commit history.
• Do not mark someone else's review comments as resolved. It is up to the reviewer who made the comment to judge whether the comment has been addressed. If you think you have addressed the comment, say so in a reply (e.g. comment "Done" or give a thumb-up reaction).
• If you need more time to implement further changes in your PR, convert it to a draft to avoid unnecessary compilation tests and mark it as ready for review again when you're done.

Further tips for contributing

It is common practice to stay in touch with PAG coordinators and PWG conveners and report regularly in meetings about ongoing work. This helps avoid duplication of efforts and makes the code writing experience and work smoother for everyone.