Skip to content

Latest commit

 

History

History
128 lines (90 loc) · 10.3 KB

CONTRIBUTING.adoc

File metadata and controls

128 lines (90 loc) · 10.3 KB
Raw

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):

  1. 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).

  2. Non-master branches, prefixed with a short name moniker (e.g. gav-my-feature) must be used for ongoing work.

  3. All modifications must be made in a pull-request to solicit feedback from other contributors.

  4. A pull-request must not be merged until CI has finished successfully.

  5. Contributors should adhere to the 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 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:

  1. Please tag each PR with exactly one A, B, C and D label at the minimum.

  2. Once a PR is ready for review please add the 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.

  3. 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. A3-inprogress is a general indicator that the PR is work in progress and 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 A8-mergeoncegreen, it is ready to merge.

  4. PRs must be tagged with their release notes requirements via the B1-B9 labels.

  5. PRs must be tagged with their release importance via the C1-C9 labels.

  6. PRs must be tagged with their audit requirements via the D1-D9 labels.

  7. PRs that must be backported to a stable branch must be tagged with E0-patchthis.

  8. PRs that introduce runtime migrations must be tagged with E1-runtimemigration. See the Migration Best Practices here for more info about how to test runtime migrations.

  9. PRs that introduce irreversible database migrations must be tagged with E2-databasemigration.

  10. PRs that add host functions must be tagged with with E4-newhostfunctions.

  11. PRs that break the external API must be tagged with E5-breaksapi.

  12. PRs that materially change the FRAME/runtime semantics must be tagged with E6-transactionversion.

  13. PRs that change the mechanism for block authoring in a backwards-incompatible way must be tagged with E7-breaksauthoring.

  14. PRs that "break everything" must be tagged with E8-breakseverything.

  15. PRs that block a new release must be tagged with E9-blocker.

  16. PRs should be categorized into projects.

  17. 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:

  1. Buggy behavior.

  2. Undue maintenance burden.

  3. Breaking with house coding style.

  4. Pessimization (i.e. reduction of speed as measured in the projects benchmarks).

  5. Feature reduction (i.e. it removes some aspect of functionality that a significant minority of users rely on).

  6. 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:

  1. There exists a somewhat cleaner/better/faster way of accomplishing the same feature/fix.

  2. 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:

  1. Pull latest Polkadot master (or clone it, if you haven’t yet).

  2. 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.)

  3. Make the changes required and build polkadot locally.

  4. Submit all this as a PR against the Polkadot Repo.

  5. In the description of your Substrate PR add "polkadot companion: [Polkadot_PR_URL]"

  6. Now you should see that the check_polkadot CI job will build your Substrate PR agains the mentioned Polkadot branch in your PR description.

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

  8. Wait for reviews on both the Substrate and the Polkadot PRs.

  9. 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 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 labels to manage PRs and issues and communicate state of a PR. Please familiarize yourself with them. Furthermore we are organizing issues in milestones. Best way to get started is to a pick a ticket from the current milestone tagged easy or medium and get going or mentor and get in contact with the mentor offering their support on that larger task.

Issues

Please label issues with the following labels:

  1. I-* Issue severity and type. EXACTLY ONE REQUIRED.

  2. P-* Issue priority. AT MOST ONE ALLOWED.

  3. Q-* Issue difficulty. AT MOST ONE ALLOWED.

  4. Z-* More general tags on the issue, denoting context and resolution.

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