pezkuwi-subxt/substrate/docs/CONTRIBUTING.adoc

= Contributing

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. No rewriting of the history after the code has been shared (e.g. through a Pull-Request).
. **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 link:STYLE_GUIDE.md[house coding style].


== Merge Process

*In General*

A Pull Request (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-criticality markers. EXACTLY ONE REQUIRED. (used by automation)
- `D-*` Audit tags denoting auditing requirements on the PR.

*Process:*

. Please tag each PR with exactly one `A`, `B`, `C` and `D` 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-please_review+[`A0-please_review`] 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-please_review` to any label `[A3, A5]` to indicate that the PR has received some feedback, but needs further work. For example. https://github.com/paritytech/substrate/labels/A3-in_progress[`A3-in_progress`] is a general indicator that the PR is work in progress.
. PRs must be tagged with their release notes requirements via the `B*` labels. If a PR should be mentioned in the release notes, use `B1` and add either: `T0-node`, `T1-runtime`or `T2-API` - this defines in which section of the release notes the PR will be shown.
. PRs must be tagged with their release importance via the `C1-C7` labels.
. PRs must be tagged with their audit requirements via the `D1-D9` labels.
. PRs that introduce runtime migrations must be tagged with https://github.com/paritytech/substrate/labels/E0-runtime_migration[`E0-runtime_migration`]. See the https://github.com/paritytech/substrate/blob/master/utils/frame/try-runtime/cli/src/lib.rs#L18[Migration Best Practices here] for more info about how to test runtime migrations.
. PRs that introduce irreversible database migrations must be tagged with https://github.com/paritytech/substrate/labels/E1-database_migration[`E1-database_migration`].
. PRs that add host functions must be tagged with with https://github.com/paritytech/substrate/labels/E3-host_functions[`E3-host_functions`].
. PRs that break the external API must be tagged with https://github.com/paritytech/substrate/labels/F3-breaks_API[`F3-breaks_API`].
. PRs that change the mechanism for block authoring in a backwards-incompatible way must be tagged with https://github.com/paritytech/substrate/labels/F1-breaks_authoring[`F1-breaks_authoring`].
. PRs that "break everything" must be tagged with https://github.com/paritytech/substrate/labels/F0-breaks_everything[`F0-breaks_everything`].
. 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:

. Buggy behavior.
. 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.

To create a Polkadot companion PR:

. Pull latest Polkadot master (or clone it, if you haven't yet).
. Override substrate deps to point to your local path or branch using https://github.com/bkchr/diener. (E.g. from the polkadot clone dir run `diener patch --crates-to-patch ../substrate --substrate` assuming substrate clone is in a sibling dir. If you do use diener, ensure that you _do not_ commit the changes diener makes to the Cargo.tomls.)
. Make the changes required and build polkadot locally.
. Submit all this as a PR against the Polkadot Repo.
. In the _description_ of your _Substrate_ PR add "polkadot companion: [Polkadot_PR_URL]"
. Now you should see that the `check_polkadot` CI job will build your Substrate PR agains the mentioned Polkadot branch in your PR description.
. Someone will need to approve the Polkadot PR before the Substrate CI will go green. (The Polkadot CI failing can be ignored as long as the polkadot job in the _substrate_ PR is green).
. Wait for reviews on both the Substrate and the Polkadot PRs.
. Once the Substrate PR runs green, a member of the `parity` github group can comment on the Substrate PR with `bot merge` which will:
    - Merge the Substrate PR.
    - The bot will push a commit to the Polkadot PR updating its Substrate reference. (effecively doing `cargo update -p sp-io`)
    - If the polkadot PR origins from a fork then a project member may need to press `approve run` on the polkadot PR.
    - The bot will merge the Polkadot PR once all its CI `{"build_allow_failure":false}` checks are green.
    Note: The merge-bot currently doesn't work with forks on org accounts, only individual accounts.
	(Hint: it's recommended to use `bot merge` to merge all substrate PRs, not just ones with a polkadot companion.)

If your PR is reviewed well, but a Polkadot PR is missing, signal it with https://github.com/paritytech/substrate/labels/E6-needs_polkadot_pr[`E6-needs_polkadot_pr`] to prevent it from getting automatically merged. In most cases the CI will add this label automatically.

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://paritytech.github.io/labels/doc_substrate.html[labels] to manage PRs and issues and communicate state of a PR. Please familiarize yourself with them. Best way to get started is to a pick a ticket tagged https://github.com/paritytech/substrate/issues?q=is%3Aissue+is%3Aopen+label%3AZ1-easy[`easy`] or https://github.com/paritytech/substrate/issues?q=is%3Aissue+is%3Aopen+label%3AZ2-medium[`medium`] and get going or https://github.com/paritytech/substrate/issues?q=is%3Aissue+is%3Aopen+label%3AZ6-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-*` or `J-*` Issue severity and type. EXACTLY ONE REQUIRED.
. `U-*` Issue urgency, suggesting in what time manner does this issue need to be resolved. AT MOST ONE ALLOWED.
. `Z-*` Issue difficulty. AT MOST ONE ALLOWED.

== Releases

Declaring formal releases remains the prerogative of the project maintainer(s).

== UI tests

UI tests are used for macros to ensure that the output of a macro doesn't change and is in the expected format. These UI tests are sensible to any changes
in the macro generated code or to switching the rust stable version. The tests are only run when the `RUN_UI_TESTS` environment variable is set. So, when
the CI is for example complaining about failing UI tests and it is expected that they fail these tests need to be executed locally. To simplify the updating
of the UI test ouput there is the `.maintain/update-rust-stable.sh` script. This can be run with `.maintain/update-rust-stable.sh CURRENT_STABLE_VERSION`
and then it will run all UI tests to update the expected output.

== 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