Skip to content

Commit

Permalink
[CONTRIBUTING] Extend contribution guidelines (patch root-project#1)
Browse files Browse the repository at this point in the history
To be squashed into previous commit before merge
  • Loading branch information
enirolf committed Jan 30, 2024
1 parent 88f9dbf commit e7b34c6
Showing 1 changed file with 26 additions and 16 deletions.
42 changes: 26 additions & 16 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,11 @@
Thank you for your interest in contributing to ROOT! We strongly welcome and appreciate such contributions!
This short guide tries to make contributing as quick and painless as possible.

> [!NOTE]
> These guidelines should be applicable to most contributes. At the same time, these are not 'one-size-fits-all' rules,
> and there might be cases where diverging from these guidelines is warranted. If you are unsure about how to structure
> your contribution, don't hesitate to reach out! We are always happy to provide help and feedback.
## Your Code Contribution

The source code for ROOT is kept in [GitHub](https://github.com/root-project/root).
Expand Down Expand Up @@ -37,10 +42,12 @@ This allows us to revert changes when needed, without affecting anything else.
### Your Commit Message

The commit summary (i.e. the first line of the commit message) should be preceded by the part of ROOT that is affected
by your commit, in square brackets. See the [commit log](https://github.com/root-project/root/commits/master/) for
examples. If you're not sure which scope you change belongs to, don't hesitate to ask! The summary itself should not
exceed 50 characters, be meaningful (i.e., it describes the change) and should be written in the
The commit summary (i.e. the first line of the commit message) should be preceded by the a tag indicating the scope of
ROOT that is affected by your commit, in square brackets. Most tags are self-describing (e.g., `[tree]` indicates a
change to TTree, `[RF]` indicates a change to RooFit). If you are unsure about which scope tags to use, we are happy to
point you in the right direction! See also the [commit log](https://github.com/root-project/root/commits/master/) for
examples. The summary itself should not exceed 50 characters (excluding the scope tag), be meaningful (i.e., it
describes the change) and should be written in the
[present imperative mood](https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/SubmittingPatches?id=HEAD#n239)
(e.g. `Add this awesome feature` instead of `Adds this awesome feature` or `Added this awesome feature`).

Expand All @@ -57,7 +64,10 @@ The commit message should be wrapped at 72 characters.
The title of your PR follows the same principle as the commit summary. If your PR only involves one commit, you can
reuse this summary. For non-functional changes (e.g. to the documentation) that don't require a ROOT build, use `[NFC]`
or `[skip-CI]` as the **first** tag in the PR title. This will prevent Jenkins from being triggered.
as the **first** tag in the PR title. This will prevent Jenkins from being triggered. If you have a functional change
for which you want to temporarily prevent Jenkins from being triggered (e.g., for a draft PR), use `[skip-CI]` as the
first tag. Note that (in most cases) this tag should be removed and Jenkins needs to be run before merging, to ensure
the change does not break anything.

The PR description describes (and in case of multiple commits, summarizes) the change in more detail.
Again, try to describe the **why** (and in this case, to a lesser extent the **what**), rather than the **how**.
Expand All @@ -74,16 +84,15 @@ Please ping people :wave: should you not get timely feedback, for instance with
## Tests

As you contribute code, this code will likely fix an issue or add a feature.
Whatever it is: this requires you to add a new test, or to extend an existing test.
We have concise unittests in the `test/` subdirectory of each part of ROOT;
see for instance [`tree/dataframe/test`](https://github.com/root-project/root/tree/master/tree/dataframe/test).
These tests are generally based on [Google Test](https://github.com/google/googletest) and easily extended.

For more involved tests, such as tests requiring custom dictionaries or data
files, we have [roottest](https://github.com/root-project/roottest.git).
Suppose for your PR you create a branch on `root.git`.
Our CI infrastructure automatically picks up a branch with the same name in your fork of `roottest.git`
and use that for testing your PR.
Whatever it is: this requires you to add a new test, or to extend an existing test. Depending on the size and complexity
of this test, it exists either in the `test/` subdirectory of each part of ROOT (see for instance
[`tree/dataframe/test`](https://github.com/root-project/root/tree/master/tree/dataframe/test)), or in
[roottest](https://github.com/root-project/roottest.git). Tests in `test/` subdirectories are unittests, mostly based on
[Google Test](https://github.com/google/googletest) and easily extended. Tests in
[roottest](https://github.com/root-project/roottest.git) are more involved (e.g., tests requiring custom dictionaries or
data files). When you create a branch in the main ROOT repository (i.e., this repository) and add a test to `roottest`,
make sure to do this under the same branch name (and open a PR for it). Our CI infrastructure automatically picks up the
changes defined in the `roottest` PR based on this branchname, and uses that for testing your PR here.

## Continuous Integration

Expand All @@ -93,7 +102,8 @@ _before_ submitting a pull request.

ROOT has automated CI tests :cop: that are used for pull requests:
- *Build and test*: a [Jenkins-based CI workflow](https://github.com/phsft-bot/build-configuration/blob/master/README.md)
as well as a GitHub Actions CI workflow tests PRs automatically; a project member might need to initiate this build.
as well as a GitHub Actions CI workflow tests PRs automatically; only a
[project member](https://github.com/orgs/root-project/people) is allowed to initiate this build.
The results are posted to the pull request.
Compared to ROOT's nightly builds, PRs are tested with less tests, on less platforms.
- *Formatting check*: `clang-format` automatically checks that a PR
Expand Down

0 comments on commit e7b34c6

Please sign in to comment.