From 33b53570c0e814558d7bf8418568e5ca47b0b529 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Ku=C4=8Dera?= Date: Sun, 1 Jun 2025 15:11:44 +0200 Subject: [PATCH] Add more details and links in contribution instructions --- docs/gettingstarted/contributingtocode.md | 29 +++++++++++++++++++---- docs/tools/README.md | 2 +- docs/troubleshooting/README.md | 3 ++- 3 files changed, 28 insertions(+), 6 deletions(-) diff --git a/docs/gettingstarted/contributingtocode.md b/docs/gettingstarted/contributingtocode.md index e7688709..81c6b4c6 100644 --- a/docs/gettingstarted/contributingtocode.md +++ b/docs/gettingstarted/contributingtocode.md @@ -19,6 +19,10 @@ Before starting to write your first piece of code, please get familiar with the and also check for more detailed instructions from your [PWG](../advanced-specifics/README.md). ``` +```tip +See the [Tools](../tools/README.md) section for suggestions on tools that can make your work with the O2Physics analysis framework much more effective. +``` + In order to contribute new code to the central repository, please follow these steps: - If you are adding a new workflow: @@ -66,17 +70,34 @@ __Give your pull request a short and meaningful title.__ ### Automatic checks -Pull requests are tested with automatic checks which get restarted whenever the commits in the PR change. +Pull requests are tested with automatic continuous-integration (CI) checks which get restarted whenever the commits in the PR change. + +The CI checks evaluate: + +- Code formatting +- Code quality + - [MegaLinter](https://megalinter.io/) + - [O2 linter](../tools/o2linter.md) +- Compilation: Verifies that the code compiles without problems on all supported platforms. +- PR properties + - Labeler: Assigns [labels](https://github.com/AliceO2Group/O2Physics/labels) to the PR based on which parts of the code base were modified. + - Title prefix checker: Verifies that the title of the PR has a valid prefix with tags corresponding to the labels. If a valid prefix is not found, it is created. + +Checks flagged as "Required" must succeed before a PR can be merged. + 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 a check fails, you can click on the name of the check 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). -```note -This means that _you do not have to format your (C++ and Python) code_, as the automatic formatting check does that for you. +```tip +_You do not have to format your (C++ and Python) code manually_. + +- You can let your PR get formatted by the automatic formatting check. +- Or you can use [pre-commit hooks](../tools/README.md#pre-commit-hooks) to format your code automatically when you make a commit. ``` ### Pull request review diff --git a/docs/tools/README.md b/docs/tools/README.md index 08810b62..a50d717c 100644 --- a/docs/tools/README.md +++ b/docs/tools/README.md @@ -67,7 +67,7 @@ This helps to apply the [Include What You Use](https://github.com/AliceO2Group/O #### Sorting `#include`s -The [`llvm-include-order`](https://clang.llvm.org/extra/clang-tidy/checks/llvm/include-order.html) check sorts `#include`s from most specific to least specific to ensure that the headers does not have any hidden dependencies. +The [`llvm-include-order`](https://clang.llvm.org/extra/clang-tidy/checks/llvm/include-order.html) check sorts `#include`s from most specific to least specific to ensure that the headers do not have any hidden dependencies. Unfortunately, the [LLVM include style](https://llvm.org/docs/CodingStandards.html#include-style) is incompatible with the [Google include style](https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes) applied by `cpplint`. diff --git a/docs/troubleshooting/README.md b/docs/troubleshooting/README.md index ff57e8c2..b21cedb2 100644 --- a/docs/troubleshooting/README.md +++ b/docs/troubleshooting/README.md @@ -107,6 +107,7 @@ If the missing table is not mentioned there, try to find the missing workflow fo | Old | New | Converter | |--------------------------------|-------------------|-------------------------------------------| | `bc` | `bc_001` | `o2-analysis-bc-converter` | +| `run2bcinfo` | `run2bcinfo_001` | `o2-analysis-run2bcinfos-converter` | | `collision` | `collision_001` | `o2-analysis-collision-converter` | | `fdd` | `fdd_001` | `o2-analysis-fdd-converter` | | `hmpid` | `hmpid_001` | `o2-analysis-hmpid-converter` | @@ -122,7 +123,7 @@ If the missing table is not mentioned there, try to find the missing workflow fo #### General cases -You can identify the missing workflow by running the [`find_dependencies.py`](https://github.com/AliceO2Group/O2Physics/blob/master/Scripts/find_dependencies.py) script. +You can identify the missing workflow by running the [dependency finder](../tools/dependencyFinder.md). The procedure is simple: If the error message complains about a missing table `DF_/O2` then you have to run `$O2PHYSICS_ROOT/share/scripts/find_dependencies.py -t
` inside the O2Physics environment and add the correct one among the listed producer workflows to your command line.