Skip to content

Commit 26fff16

Browse files
committed
Contributing: Add details on development and pull requests
1 parent 7ec46d0 commit 26fff16

1 file changed

Lines changed: 22 additions & 3 deletions

File tree

docs/gettingstarted/contributingtocode.md

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,13 @@ Before starting to write your first piece of code, please get familiar with the
1919
and also check for more detailed instructions from your [PWG](../advanced-specifics/README.md).
2020
```
2121

22-
```tip
23-
See the [Tools](../tools/README.md) section for suggestions on tools that can make your work with the O2Physics analysis framework much more effective.
22+
```note
23+
See the [Tools](../tools/README.md) section for further instructions and for suggestions on tools that can make your work with the O2Physics analysis framework much more effective.
2424
```
2525

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

28+
- Update your O2Physics installation.
2829
- If you are adding a new workflow:
2930
- Place your `cxx` file in the appropriate directory (see the [O2Physics repository structure](theo2physicsrepo.md)).
3031
- Add the workflow compilation instructions in the `CMakeLists.txt` (you can clone one of the existing `o2physics_add_dpl_workflow` blocks).
@@ -33,7 +34,10 @@ In order to contribute new code to the central repository, please follow these s
3334
- Make sure the compilation of your code does not produce any errors or warnings.
3435
- 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.
3536
- Test your code.
37+
- Verify that the new code runs successfully and without warnings or errors.
38+
- Validate the output of the new code.
3639
- Commit your changes and push them to your remote fork repository on GitHub.
40+
- See [How to write a Git commit message](../gettingstarted/gitbasics.md#how-to-write-a-git-commit-message).
3741
- [Create a pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)
3842
from your fork repository to the main repository.
3943

@@ -64,9 +68,19 @@ __Keep pull requests small and focused.__
6468

6569
__Give your pull request a short and meaningful title.__
6670

67-
- The title should be informative enough to give an idea of _what_ was changed and _where_.
71+
- The title should be a brief summary of _what_ was changed and _where_.
72+
- To specify _where_, you can use a prefix with the name of the file or of the analysis or of the framework component.
73+
- A tag prefix with names of concerned directories is added automatically. (See [Automatic checks](#automatic-checks).) It can be extended with additional details using `,` (e.g. JIRA ticket) or `/` (for subdirectory names).
74+
- Example: "[PWGHF/D2H] taskD0: Add centrality histogram"
6875
- Further details (e.g. _why_ this change is needed or related links) can be provided in the description below the title.
6976
- Examples of too vague titles: "Test", "Fix bug", "Add new parameter", "Update cuts", "Improve code".
77+
- See [How to write a Git commit message](../gettingstarted/gitbasics.md#how-to-write-a-git-commit-message).
78+
79+
__Do not duplicate pull requests.__
80+
81+
- Duplicating a PR duplicates review efforts and usage of testing resources and it almost certainly does not solve your problem.
82+
- Use `git push` to update your PR. (Avoid `--force` if possible. See [Pull request review](#pull-request-review).)
83+
- Exception: Replacing a PR makes sense, if the PR contains unwanted unrelated changes which have notified unrelated code owners and you want to stop spamming them further.
7084

7185
### Automatic checks
7286

@@ -83,6 +97,8 @@ The CI checks evaluate:
8397
- Labeler: Assigns [labels](https://github.com/AliceO2Group/O2Physics/labels) to the PR based on which parts of the code base were modified.
8498
- 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.
8599

100+
__In general, a PR should not be merged if it does not pass all checks, unless there are good reasons to ignore the errors and warnings.__
101+
86102
Checks flagged as "Required" must succeed before a PR can be merged.
87103

88104
The compilation checks ("build/...") run only on PRs marked as ready for review (i.e. not on draft PRs).
@@ -100,6 +116,9 @@ _You do not have to format your (C++ and Python) code manually_.
100116
- Or you can use [pre-commit hooks](../tools/README.md#pre-commit-hooks) to format your code automatically when you make a commit.
101117
```
102118

119+
PRs are marked as stale after 30 days of no activity and closed 5 days later if still inactive.
120+
(Events unrelated to the commit history (e.g. automatic comments from failed builds) can reset the timestamp which can prevent obsolete PRs from getting closed automatically.)
121+
103122
### Pull request review
104123

105124
The approvers (code owners) are listed in the

0 commit comments

Comments
 (0)