Newer
Older
Afri Schoedon
committed
The `Substrate` project is an **OPENISH Open Source Project**
== What?
Individuals making significant and valuable contributions are given commit-access to a project to contribute as they see fit. A project is more like an open wiki than a standard guarded open source project.
== Rules
There are a few basic ground-rules for contributors (including the maintainer(s) of the project):
. **No `--force` pushes** or modifying the master branch history in any way. If you need to rebase, ensure you do it in your own repo.
. **Non-master branches**, prefixed with a short name moniker (e.g. `gav-my-feature`) must be used for ongoing work.
. **All modifications** must be made in a **pull-request** to solicit feedback from other contributors.
. A pull-request *must not be merged until CI* has finished successfully.
. Contributors should adhere to the https://wiki.parity.io/Substrate-Style-Guide[house coding style].
== Merge Process
A PR needs to be reviewed and approved by project maintainers unless:
- it does not alter any logic (e.g. comments, dependencies, docs), then it may be tagged https://github.com/paritytech/substrate/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3AA2-insubstantial[`insubstantial`] and merged by its author once CI is complete.
- it is an urgent fix with no large change to logic, then it may be merged after a non-author contributor has approved the review once CI is complete.
*Labels TLDR:*
- `A-*` Pull request status. ONE REQUIRED.
- `B-*` Changelog and/or Runtime-upgrade post composition markers. ONE REQUIRED. (used by automation)
- `C-*` Release notes release-priority markers. EXACTLY ONE REQUIRED. (used by automation)
- `D-*` More general tags on the PR denoting various implications and requirements.
*Process:*
. Please tag each PR with exactly one `A`, `B` and `C` label at the minimum.
. Once a PR is ready for review please add the https://github.com/paritytech/substrate/pulls?q=is%3Apr+is%3Aopen+label%3AA0-pleasereview[`A0-pleasereview`] label. Generally PRs should sit with this label for 48 hours in order to garner feedback. It may be merged before if all relevant parties had a look at it.
. If the first review is not an approval, swap `A0-pleasereview` to any label `[A3, A7]` to indicate that the PR has received some feedback, but needs further work. For example. https://github.com/paritytech/substrate/labels/A3-inprogress[`A3-inprogress`] is a general indicator that the PR is work in progress and https://github.com/paritytech/substrate/labels/A4-gotissues[`A4-gotissues`] means that it has significant problems that need fixing. Once the work is done, change the label back to `A0-pleasereview`. You might end up swapping a few times back and forth to climb up the A label group. Once a PR is https://github.com/paritytech/substrate/labels/A8-mergeoncegreen[`A8-mergeoncegreen`], it is ready to merge.
. PRs must be tagged with respect to _release notes_ with https://github.com/paritytech/substrate/labels/B0-silent[`B0-silent`] and `B1-..`. The former indicates that no changes should be mentioned in any release notes. The latter indicates that the changes should be reported in the corresponding release note
. PRs that break the external API must be tagged with https://github.com/paritytech/substrate/labels/D2-breaksapi[`D2-breaksapi`], when it changes the FRAME or consensus of running system with https://github.com/paritytech/substrate/labels/B3-breaksconsensus[`B3-breaksconsensus`].
. PRs should be labeled with their release importance via the `C1-C9`.
. PRs should be categorized into projects.
. No PR should be merged until all reviews' comments are addressed and CI is successful.
*Reviewing pull requests*:
When reviewing a pull request, the end-goal is to suggest useful changes to the author. Reviews should finish with approval unless there are issues that would result in:
. Undue maintenance burden.
. Breaking with house coding style.
. Pessimization (i.e. reduction of speed as measured in the projects benchmarks).
. Feature reduction (i.e. it removes some aspect of functionality that a significant minority of users rely on).
. Uselessness (i.e. it does not strictly add a feature or fix a known issue).
*Reviews may not be used as an effective veto for a PR because*:
. There exists a somewhat cleaner/better/faster way of accomplishing the same feature/fix.
. It does not fit well with some other contributors' longer-term vision for the project.
=== Updating Polkadot as well
**All pull requests will be checked against either Polkadot master, or your provided Polkadot companion PR**. That is, If your PR changes the external APIs or interfaces used by Polkadot. If you tagged the PR with `breaksapi` or `breaksconsensus` this is most certainly the case, in all other cases check for it by running step 1 below.
. Pull latest Polkadot master (or clone it, if you haven't yet).
. Override your local cargo config to point to your local substrate (pointing to your WIP branch): place `paths = ["path/to/substrate"]` in `~/.cargo/config`.
. Make the changes required and build polkadot locally.
. Submit all this as a PR against the Polkadot Repo. Link to your Polkadot PR in the _description_ of your Substrate PR as "polkadot companion: [URL]" OR use the same name for your Polkdadot branch as the Substrate branch.
. Now you should see that the `check_polkadot` CI job will build your Substrate PR agains the mentioned Polkadot branch in your PR description.
. Wait for reviews on both
. Once both PRs have been green lit, they can both be merged 🍻.
If your PR is reviewed well, but a Polkadot PR is missing, signal it with https://github.com/paritytech/substrate/labels/A7-needspolkadotpr[`A7-needspolkadotpr`] to prevent it from getting automatically merged.
As there might be multiple pending PRs that might conflict with one another, a) you should not merge the substrate PR until the Polkadot PR has also been reviewed and b) both should be merged pretty quickly after another to not block others.
== Helping out
We use https://github.com/paritytech/substrate/labels[labels] to manage PRs and issues and communicate state of a PR. Please familiarize yourself with them. Furthermore we are organizing issues in https://github.com/paritytech/substrate/milestones[milestones]. Best way to get started is to a pick a ticket from the current milestone tagged https://github.com/paritytech/substrate/issues?q=is%3Aissue+is%3Aopen+label%3AQ2-easy[`easy`] or https://github.com/paritytech/substrate/issues?q=is%3Aissue+is%3Aopen+label%3AQ3-medium[`medium`] and get going or https://github.com/paritytech/substrate/issues?q=is%3Aissue+is%3Aopen+label%3AX1-mentor[`mentor`] and get in contact with the mentor offering their support on that larger task.
== Issues
Please label issues with the following labels:
. `I-*` Issue severity and type. EXACTLY ONE REQUIRED.
. `P-*` Issue priority. AT MOST ONE ALLOWED.
. `Q-*` Issue difficulty. AT MOST ONE ALLOWED.
. `Z-*` More general tags on the issue, denoting context and resolution.
== Releases
Declaring formal releases remains the prerogative of the project maintainer(s).
== Changes to this arrangement
This is an experiment and feedback is welcome! This document may also be subject to pull-requests or changes by contributors where you believe you have something valuable to add or change.
== Heritage
These contributing guidelines are modified from the "OPEN Open Source Project" guidelines for the Level project: https://github.com/Level/community/blob/master/CONTRIBUTING.md