Skip to content

Commit

Permalink
[CONTRIBUTING] Extend contribution guidelines
Browse files Browse the repository at this point in the history
This follows the proposal and discussion during the ROOT team meeting
on 22/01/2024 (https://indico.cern.ch/event/1368009/).
  • Loading branch information
enirolf committed Jan 23, 2024
1 parent 12ebada commit 88f9dbf
Showing 1 changed file with 57 additions and 17 deletions.
74 changes: 57 additions & 17 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,35 +1,77 @@

How to Contribute Code to ROOT
==============================
# How to Contribute Code to ROOT

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.

Your Pull Request
-----------------------
## Your Code Contribution

The source code for ROOT is kept in [GitHub](https://github.com/root-project/root).
Changes go through pull requests ("PRs").
The primary branch for development is `master`.
Visit [this page](https://root.cern/for_developers/creating_pr) for the mechanics on how to
create pull requests.

> [!IMPORTANT]
> We require PRs to cleanly apply to master without a merge commit, i.e. through "fast-forward".
> Please follow the [coding conventions](https://root.cern.ch/coding-conventions), as this is a simple item for
> reviewers to otherwise get stuck on.
> To make your (and our own) life easier, we provide a
> [`clang-format` configuration file](https://github.com/root-project/root/blob/master/.clang-format).
By providing code, you agree to transfer your copyright on the code to the "ROOT project".
Of course you will be duly credited: for sizable contributions your name will appear in the
[CREDITS](https://raw.githubusercontent.com/root-project/root/master/README/CREDITS){:target="_blank"}
[CREDITS](https://raw.githubusercontent.com/root-project/root/master/README/CREDITS)
file shipped with every binary and source distribution.
The copyright transfer helps us with effectively defending the project in case of litigation.

:warning: We require PRs to cleanly apply to master without a merge commit, i.e. through "fast-forward".
Please follow the [coding conventions](https://root.cern.ch/coding-conventions),
as this is a simple item for reviewers to otherwise get stuck on.
## Your Commit

Each commit is a self-contained, _atomic_ change. This means that:
1. **Each commit should be able to successfully build ROOT.**
Doing so makes traveling through the git history, for example during a `git bisect` much easier.
Ideally, the commit also should not depend on other commits to _run_ ROOT.
2. **Each commit does not contain more than one independent change.**
This allows us to revert changes when needed, without affecting anything else.

> [!TIP]
> During a code review, it may be useful to make smaller commits to track intermediate changes, and rebase after the PR
> is approved to ensure the above points are met and to reduce clutter.
### 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
[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`).

The commit message that follow the summary can be used to provide more context to the change.
It should describe the **why**, rather than the **what** and **how** (we can gather this from the commit summary and the
change diff, respectively).
The commit message should be wrapped at 72 characters.

## Your Pull Request

> [!NOTE]
> For the mechanics on how to create pull requests, please visit
> [this page](https://root.cern/for_developers/creating_pr).
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.

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**.

If your PR is related to an open [issue](https://github.com/root-project/root/issues), make sure to link it.
This will be done automatically if you add
[closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
to the PR description.

Once a PR is created, a member of the ROOT team will review it as quickly as possible. If you are familiar with the
ROOT community, it may be beneficial to add a suggested reviewer to the PR in order to get quicker attention.
Please ping people :wave: should you not get timely feedback, for instance with `@root-project/core ping!`

Tests
-----
## 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.
Expand All @@ -43,17 +85,15 @@ 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.


Continuous Integration
----------------------
## Continuous Integration

To prevent bad surprises and make a better first impression, we
strongly encourage new developers to [run the tests](https://root.cern/for_developers/run_the_tests/)
_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)
tests PRs automatically; a project member might need to initiate this build.
as well as a GitHub Actions CI workflow tests PRs automatically; a project member might need 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 88f9dbf

Please sign in to comment.