diff --git a/cumulus/docs/documentation.md b/cumulus/docs/documentation.md deleted file mode 100644 index 383f7ff3c405..000000000000 --- a/cumulus/docs/documentation.md +++ /dev/null @@ -1 +0,0 @@ -Was moved [here](https://github.com/paritytech/labels/blob/main/docs/doc_cumulus.md) \ No newline at end of file diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md new file mode 100644 index 000000000000..1a9f21de775c --- /dev/null +++ b/docs/CODE_OF_CONDUCT.md @@ -0,0 +1,76 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers +pledge to making participation in our project and our community a harassment-free experience for +everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level +of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic address, without explicit + permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +### Facilitation, Not Strongarming + +We recognize that this software is merely a tool for users to create and maintain their blockchain +of preference. We see that blockchains are naturally community platforms with users being the +ultimate decision makers. We assert that good software will maximize user agency by facilitating +user-expression on the network. As such: + +* This project will strive to give users as much choice as is both reasonable and possible over what + protocol they adhere to; but +* Use of the project's technical forums, commenting systems, pull requests and issue trackers as a + means to express individual protocol preferences is forbidden. + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are +expected to take appropriate and fair corrective action in response to any instances of unacceptable +behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, +code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to +ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces when an individual is +representing the project or its community. Examples of representing a project or community include +using an official project e-mail address, posting via an official social media account, or acting as +an appointed representative at an online or offline event. Representation of a project may be further +defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting +the project team at . The project team will review and investigate all complaints, +and will respond in a way that it deems appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. Further details of +specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary +or permanent repercussions as determined by other members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at +https://contributor-covenant.org/version/1/4 + +[homepage]: https://contributor-covenant.org diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 000000000000..fa850f6bdc2e --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,128 @@ +# Contributing + +The `Polkadot SDK` project is an **OPENISH Open Source Project** + +## What? + +Individuals making significant and valuable contributions are given commit-access to the project. +Contributions are done via pull-requests and need to be approved by the maintainers. + +## 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](./STYLE_GUIDE.md). +6. Contributors should adhere to the [house documenting style](./DOCUMENTATION_GUIDELINES.md), when applicable. + +## Merge Process + +### In General + +A Pull Request (PR) needs to be reviewed and approved by project maintainers. +If a change does not alter any logic (e.g. comments, dependencies, docs), then it may be tagged +`A1-insubstantial` and merged faster. +If it is an urgent fix with no large change to logic, then it may be merged after a non-author +contributor has reviewed it well and approved the review once CI is complete. +No PR should be merged until all reviews' comments are addressed. + +### Labels: + +The set of labels and their description can be found [here](linktobeinserted) + +### Process: + +1. Please use our [Pull Request Template](./PULL_REQUEST_TEMPLATE.md) and make sure all relevant + information is reflected in your PR. +2. Please tag each PR with minimum one `T*` label. The respective `T*` labels should signal the + component that was changed, they are also used by downstream users to track changes and to + include these changes properly into their own releases. +3. If your’re still working on your PR, please submit as “Draft”. Once a PR is ready for review change + the status to “Open”, so that the maintainers get to review your PR. Generally PRs should sit for + 48 hours in order to garner feedback. It may be merged before if all relevant parties had a look at it. +4. If you’re introducing a major change, that might impact the documentation please add the label + `T13-documentation`. The docs team will get in touch. +5. If your PR changes files in these paths: + + `polkadot` : '^runtime/polkadot' + `polkadot` : '^runtime/kusama' + `polkadot` : '^primitives/src/' + `polkadot` : '^runtime/common' + `substrate` : '^frame/' + `substrate` : '^primitives/' + + It should be added to the [security audit board](https://github.com/orgs/paritytech/projects/103) + and will need to undergo an audit before merge. +6. PRs will be able to be merged once all reviewers' comments are addressed and CI is successful. + +**Noting breaking changes:** +When breaking APIs, the PR description should mention what was changed alongside some examples on how +to change the code to make it work/compile. +It should also mention potential storage migrations and if they require some special setup aside adding +it to the list of migrations in the runtime. + +## 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). + +The reviewers are also responsible to check: + +a) if a changelog is necessary and attached + +b) the quality of information in the changelog file + +c) the PR has an impact on docs + +d) that the docs team was included in the review process of a docs update + +**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. + +## Helping out + +We use [labels](https://github.com/paritytech/polkadot-sdk/labels) to manage PRs and issues and communicate +state of a PR. Please familiarise yourself with them. Best way to get started is to a pick a ticket tagged +`[easy](https://github.com/paritytech/polkadot-sdk/issues?q=is%3Aopen+is%3Aissue+label%3AD0-easy)` +or `[medium](https://github.com/paritytech/polkadot-sdk/issues?q=is%3Aopen+is%3Aissue+label%3AD1-medium)` +and get going or `[mentor](https://github.com/paritytech/polkadot-sdk/issues?q=is%3Aopen+is%3Aissue+label%3AC1-mentor)` +and get in contact with the mentor offering their support on that larger task. + +**** + +### Issues + +If what you are looking for is an answer rather than proposing a new feature or fix, search +[https://substrate.stackexchange.com](https://substrate.stackexchange.com/) to see if an post already +exists, and ask if not. Please do not file support issues here. +Before opening a new issue search to see if a similar one already exists and leave a comment that you +also experienced this issue or add your specifics that are related to an existing issue. +Please label issues with the following labels: +1. `I*` issue severity and type. EXACTLY ONE REQUIRED. +2. `D*` issue difficulty, suggesting the level of complexity this issue has. AT MOST ONE ALLOWED. +3. `T*` Issue topic. MULTIPLE 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 diff --git a/substrate/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINE.md similarity index 56% rename from substrate/docs/DOCUMENTATION_GUIDELINES.md rename to docs/DOCUMENTATION_GUIDELINE.md index 0f83f5e6445d..823617329590 100644 --- a/substrate/docs/DOCUMENTATION_GUIDELINES.md +++ b/docs/DOCUMENTATION_GUIDELINE.md @@ -1,8 +1,11 @@ # Substrate Documentation Guidelines -This document is only focused on documenting parts of substrate that relates to its external API. The list of such crates can be found in [CODEOWNERS](./CODEOWNERS). Search for the crates that are auto-assigned to a team called `docs-audit`. +This document is focused on documenting parts of substrate that relate to its +external API. The list of such crates can be found in [CODEOWNERS](./CODEOWNERS). +Search for the crates auto-assigned to the `docs-audit` team. -These are crates that are often used by external developers and need more thorough documentation. These are the crates most concerned with FRAME development. +These crates are used by external developers and need thorough documentation. +They are the most concerned with FRAME development. - [Substrate Documentation Guidelines](#substrate-documentation-guidelines) - [General/Non-Pallet Crates](#generalnon-pallet-crates) @@ -21,6 +24,7 @@ These are crates that are often used by external developers and need more thorou - [Storage Items](#storage-items) - [Errors and Events](#errors-and-events) +--- ## General/Non-Pallet Crates @@ -28,18 +32,25 @@ First, consider the case for all such crates, except for those that are pallets. ### What to Document? -The first question is, what should you document? Use the following filter: +The first question is, what should you document? Use this filter: 1. In the crates assigned to `docs-audit` in [CODEOWNERS](./CODEOWNERS), -2. All `pub` item need to be documented. If it is not `pub`, it does not appear in the rust-docs, and is not public facing. - * Within `pub` items, sometimes they are only `pub` in order to be used by another internal crate, and you can foresee that this will not be used by anyone else other than you. These need **not** be documented thoroughly, and are left to your discretion to identify. - * Reminder: `trait` items are public by definition, if the trait is public. -3. All public modules (`mod`) should have reasonable module-level documentation (`//!`). +2. All `pub` items need to be documented. If not `pub`, it doesn't appear in the +rust-docs, and is not public facing. + + * Within `pub` items, sometimes they are only `pub` to be used by another + internal crate, and you can foresee that this won't be used by anyone else. + These need **not** be documented thoroughly. + + * Reminder: `trait` items are public by definition if the trait is public. +3. All public modules (`mod`) should have reasonable module-level documentation (`//!`). #### Rust Docs vs. Code Comments -Note that anything starting with `///` is an external rust-doc, and everything starting with `//` does not appear in the rust-docs. It's important to not confuse the two in your documentation. +Note that anything starting with `///` is an external rust-doc, and everything +starting with `//` does not appear in the rust-docs. +It's important to not confuse the two in your documentation. ```rust /// Computes the square root of the input, returning `Ok(_)` if successful. @@ -55,70 +66,124 @@ pub fn sqrt(x: u32) -> Result { } ``` +--- + ### How to Document? -There are a few very good sources that you can look into: +There are good sources to look into: -- https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html -- https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/documentation.html -- https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate +- [Rust Documentation Guide](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html) +- [Documentation in Rust Book](https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments) +- [Guide on Writing Documentation for a Rust Crate](https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate) -As mentioned [here](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/documentation.html#writing-documentation-comments) and [here](https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate), always start with a **single sentence** demonstrating what is being documented. All additional documentation should be added *after a newline*. Strive to make the first sentence succinct and short. The reason for this is the first paragraph of docs about an item (everything before the first newline) is used as the excerpt that rust doc displays about this item when it appears in tables, such as the table listing all functions in a module. If this excerpt is too long, the module docs will be very difficult to read. +As mentioned [here](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/documentation.html#writing-documentation-comments) and [here](https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate), +always start with a **single sentence** demonstrating what is documented. All additional +documentation should be added *after a newline*. Strive to make the first sentence succinct +and short.The reason for this is the first paragraph of docs about an item (everything +before the first newline) is used as the excerpt that rust doc displays about +this item when it appears in tables, such as the table listing all functions in +a module. If this excerpt is too long, the module docs will be very difficult +to read. About [special sections](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/documentation.html#special-sections), we will most likely not need to think about panic and safety in any runtime related code. Our code is never `unsafe`, and will (almost) never panic. -Use `# Examples as much as possible. These are great ways to further demonstrate what your APIs are doing, and add free test coverage. As an additional benefit, any code in rust-docs is treated as an "integration tests", not unit tests, which tests your crate in a different way than unit tests. So, it is both a win for "more documentation" and a win for "more test coverage". - -You can also consider having an `# Error` section optionally. Of course, this only applies if there is a `Result` being returned, and if the `Error` variants are overly complicated. - -Strive to include correct links to other items in your written docs as much as possible. In other words, avoid `` `some_func` `` and instead use ``[`some_func`]``. -Read more about how to correctly use links in your rust-docs [here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html#valid-links) and [here](https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#additions-to-the-documentation-syntax). - - -> While you are linking, you might become conscious of the fact that you are in need of linking to (too many) foreign items in order to explain your API. This is leaning more towards API-Design rather than documentation, but it is a warning that the subject API might be slightly wrong. For example, most "glue" traits[^1] in `frame/support` should be designed and documented without making hard assumptions about particular pallets that implement them. +Use `# Examples as much as possible. These are great ways to further +demonstrate what your APIs are doing, and add free test coverage. As an +additional benefit, any code in rust-docs is treated as an "integration tests", +not unit tests, which tests your crate in a different way than unit tests. So, +it is both a win for "more documentation" and a win for "more test coverage". + +You can also consider having an `# Error` section optionally. Of course, this +only applies if there is a `Result` being returned, and if the `Error` variants +are overly complicated. + +Strive to include correct links to other items in your written docs as much as +possible. In other words, avoid \`some_func\` and instead use \[\`some_fund\`\]. +Read more about how to correctly use links in your rust-docs +[here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html#valid-links) +and [here](https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#additions-to-the-documentation-syntax). +Strive to include correct links to other items in your written docs as much as +possible. In other words, avoid `` `some_func` `` and instead use +``[`some_func`]``. + +> While you are linking, you might become conscious of the fact that you are +in need of linking to (too many) foreign items in order to explain your API. +This is leaning more towards API-Design rather than documentation, but it is a +warning that the subject API might be slightly wrong. For example, most "glue" +traits[^1] in `frame/support` should be designed and documented without making +hard assumptions about particular pallets that implement them. + +--- #### TLDR -0. Have the goal of enforcing `#![deny(missing_docs)]` mentally, even if it is not enforced by the compiler 🙈. -1. Start with a single, clear and concise sentence. Follow up with more context, after a newline, if needed. +0. Have the goal of enforcing `#![deny(missing_docs)]` mentally, even if it is +not enforced by the compiler 🙈. +1. Start with a single, clear and concise sentence. Follow up with more context, +after a newline, if needed. 2. Use examples as much as reasonably possible. 3. Use links as much as possible. -4. Think about context. If you are explaining a lot of foreign topics while documenting a trait that should not explicitly depend on them, you have likely not designed it properly. +4. Think about context. If you are explaining a lot of foreign topics while +documenting a trait that should not explicitly depend on them, you have likely +not designed it properly. + +--- #### Proc-Macros -Note that there are special considerations when documenting proc macros. Doc links will appear to function _within_ your proc macro crate, but often will no longer function when these proc macros are re-exported elsewhere in your project. The exception is doc links to _other proc macros_ which will function just fine if they are also being re-exported. It is also often necessary to disambiguate between a proc macro and a function of the same name, which can be done using the `macro@my_macro_name` syntax in your link. Read more about how to correctly use links in your rust-docs [here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html#valid-links) and [here](https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#additions-to-the-documentation-syntax). +Note that there are special considerations when documenting proc macros. Doc +links will appear to function _within_ your proc macro crate, but often will no +longer function when these proc macros are re-exported elsewhere in your +project. The exception is doc links to _other proc macros_ which will function +just fine if they are also being re-exported. It is also often necessary to +disambiguate between a proc macro and a function of the same name, which can be +done using the `macro@my_macro_name` syntax in your link. Read more about how to +correctly use links in your rust-docs [here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html#valid-links) +and [here](https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#additions-to-the-documentation-syntax). +--- ### Other Guidelines -The above five guidelines must always be reasonably respected in the documentation. +The above five guidelines must always be reasonably respected in the +documentation. -The following are a set of notes that may not necessarily hold in all circumstances: +The following are a set of notes that may not necessarily hold in all +circumstances: +--- #### Document Through Code -You should make sure that your code is properly-named and well-organized so that your code functions as a form of documentation. However, within the complexity of our projects in Polkadot/Substrate that is not enough. Particularly, things like examples, errors and panics cannot be documented only through properly-named and well-organized code. - -> Our north star is self-documenting code that also happens to be well-documented and littered with examples. +You should make sure that your code is properly-named and well-organized so that +your code functions as a form of documentation. However, within the complexity +of our projects in Polkadot/Substrate that is not enough. Particularly, things +like examples, errors and panics cannot be documented only through properly- +named and well-organized code. +> Our north star is self-documenting code that also happens to be well-documented +and littered with examples. -* Your written documents should *complement* the code, not *repeat* it. As an example, a documentation on top of a code example should never look like the following: +* Your written documents should *complement* the code, not *repeat* it. As an +example, a documentation on top of a code example should never look like the +following: - ```rust +```rust /// Sends request and handles the response. trait SendRequestAndHandleResponse { } ``` -In the above example, the documentation has added no useful information not already contained within the properly-named trait and is redundant. +In the above example, the documentation has added no useful information not +already contained within the properly-named trait and is redundant. +--- #### Formatting Matters -The way you format your documents (newlines, heading and so on) makes a difference. Consider the below examples: +The way you format your documents (newlines, heading and so on) makes a +difference. Consider the below examples: ```rust /// This function works with input u32 x and multiplies it by two. If @@ -141,18 +206,32 @@ fn multiply_by_2(x: u32) -> u32 { .. } // More efficiency can be achieved if we improve this via such and such. fn multiply_by_2(x: u32) -> u32 { .. } ``` +They are both roughly conveying the same set of facts, but one is easier to +follow because it was formatted cleanly. Especially for traits and types that +you can foresee will be seen and used a lot, try and write a well formatted +version. -They are both roughly conveying the same set of facts, but one is easier to follow because it was formatted cleanly. Especially for traits and types that you can foresee will be seen and used a lot, try and write a well formatted version. - -Similarly, make sure your comments are wrapped at 100 characters line-width (as defined by our [`rustfmt.toml`](../rustfmt.toml)), no **more and no less**! The more is fixed by `rustfmt` and our CI, but if you (for some unknown reason) wrap your lines at 59 characters, it will pass the CI, and it will not look good 🫣. Consider using a plugin like [rewrap](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap) (for Visual Studio Code) to properly do this. +Similarly, make sure your comments are wrapped at 100 characters line-width (as +defined by our [`rustfmt.toml`](../rustfmt.toml)), no **more and no less**! The +more is fixed by `rustfmt` and our CI, but if you (for some unknown reason) +wrap your lines at 59 characters, it will pass the CI, and it will not look good +🫣. Consider using a plugin like [rewrap](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap) (for Visual Studio Code) to properly do this. [^1]: Those that help two pallets talk to each other. +--- + + ## Pallet Crates -The guidelines so far have been general in nature, and are applicable to crates that are pallets and crates that're not pallets. +The guidelines so far have been general in nature, and are applicable to crates +that are pallets and crates that're not pallets. -The following is relevant to how to document parts of a crate that is a pallet. See [`pallet-fast-unstake`](../frame/fast-unstake/src/lib.rs) as one examples of adhering these guidelines. +The following is relevant to how to document parts of a crate that is a pallet. +See [`pallet-fast-unstake`](../frame/fast-unstake/src/lib.rs) as one example of +adhering these guidelines. + +--- ### Top Level Pallet Docs (`lib.rs`) @@ -204,15 +283,24 @@ For the top-level pallet docs, consider the following template: //! ``` -This template's details (heading 3s and beyond) are left flexible, and at the discretion of the developer to make the best final choice about. For example, you might want to include `### Terminology` or not. Moreover, you might find it more useful to include it in `## Overview`. -Nonetheless, the high level flow of going from the most high level explanation to the most low level explanation is important to follow. +This template's details (heading 3s and beyond) are left flexible, and at the +discretion of the developer to make the best final choice about. For example, +you might want to include `### Terminology` or not. Moreover, you might find it +more useful to include it in `## Overview`. + +Nonetheless, the high level flow of going from the most high level explanation +to the most low level explanation is important to follow. + +As a rule of thumb, the Heading 2s (`##`) in this template can be considered a +strict rule, while the Heading 3s (`###`) and beyond are flexible. -As a rule of thumb, the Heading 2s (`##`) in this template can be considered a strict rule, while the Heading 3s (`###`) and beyond are flexible. +--- #### Polkadot and Substrate -Optionally, in order to demonstrate the relation between the two, you can start the pallet documentation with: +Optionally, in order to demonstrate the relation between the two, you can start +the pallet documentation with: ``` //! > Made with *Substrate*, for *Polkadot*. @@ -224,6 +312,8 @@ Optionally, in order to demonstrate the relation between the two, you can start //! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github ``` +--- + ### Dispatchables For each dispatchable (`fn` item inside `#[pallet::call]`), consider the following template: @@ -251,14 +341,27 @@ pub fn name_of_dispatchable(origin: OriginFor, ...) -> DispatchResult {} Consider the fact that these docs will be part of the metadata of the associated dispatchable, and might be used by wallets and explorers. +--- + ### Storage Items -1. If a map-like type is being used, always note the choice of your hashers as private code docs (`// Hasher X chosen because ...`). Recall that this is not relevant information to external people, so it must be documented as `//`. -2. Consider explaining the crypto-economics of how a deposit is being taken in return of the storage being used. -3. Consider explaining why it is safe for the storage item to be unbounded, if `#[pallet::unbounded]` or `#[pallet::without_storage_info]` is being used. +1. If a map-like type is being used, always note the choice of your hashers as +private code docs (`// Hasher X chosen because ...`). Recall that this is not +relevant information to external people, so it must be documented as `//`. + +2. Consider explaining the crypto-economics of how a deposit is being taken in +return of the storage being used. + +3. Consider explaining why it is safe for the storage item to be unbounded, if +`#[pallet::unbounded]` or `#[pallet::without_storage_info]` is being used. + +--- ### Errors and Events -Consider the fact that, similar to dispatchables, these docs will be part of the metadata of the associated event/error, and might be used by wallets and explorers. +Consider the fact that, similar to dispatchables, these docs will be part of +the metadata of the associated event/error, and might be used by wallets and +explorers. -Specifically for `error`, explain why the error has happened, and what can be done in order to avoid it. +Specifically for `error`, explain why the error has happened, and what can be +done in order to avoid it. diff --git a/substrate/docs/PULL_REQUEST_TEMPLATE.md b/docs/PULL_REQUEST_TEMPLATE.md similarity index 73% rename from substrate/docs/PULL_REQUEST_TEMPLATE.md rename to docs/PULL_REQUEST_TEMPLATE.md index d2bb22f6e245..15482d9e85a8 100644 --- a/substrate/docs/PULL_REQUEST_TEMPLATE.md +++ b/docs/PULL_REQUEST_TEMPLATE.md @@ -2,7 +2,11 @@ ✄ ----------------------------------------------------------------------------- -Thank you for your Pull Request! 🙏 Please make sure it follows the contribution guidelines outlined in [this document](https://github.com/paritytech/substrate/blob/master/docs/CONTRIBUTING.md) and fill out the sections below. Once you're ready to submit your PR for review, please delete this section and leave only the text under the "Description" heading. +Thank you for your Pull Request! 🙏 Please make sure it follows the contribution +guidelines outlined in [this document](CONTRIBUTING.md) and fill out the +sections below. Once you're ready to submit your PR for review, please delete +this section and leave only the text under the "Description" heading. + # Description @@ -25,7 +29,7 @@ Cumulus companion: (*if applicable*) # Checklist - [ ] My PR includes a detailed description as outlined in the "Description" section above -- [ ] My PR follows the [labeling requirements](https://github.com/paritytech/substrate/blob/master/docs/CONTRIBUTING.md#merge-process) of this project (at minimum one label for each `A`, `B`, `C` and `D` required) +- [ ] My PR follows the [labeling requirements](CONTRIBUTING.md#Process) of this project (at minimum one label for `T` required) - [ ] I have made corresponding changes to the documentation (if applicable) - [ ] I have added tests that prove my fix is effective or that my feature works (if applicable) - [ ] If this PR alters any external APIs or interfaces used by Polkadot, the corresponding Polkadot PR is ready as well as the corresponding Cumulus PR (optional) diff --git a/polkadot/SECURITY.md b/docs/SECURITY.md similarity index 69% rename from polkadot/SECURITY.md rename to docs/SECURITY.md index db81bcaab4d0..b6559efdf976 100644 --- a/polkadot/SECURITY.md +++ b/docs/SECURITY.md @@ -1,10 +1,17 @@ + + # Security Policy -Parity Technologies is committed to resolving security vulnerabilities in our software quickly and carefully. We take the necessary steps to minimize risk, provide timely information, and deliver vulnerability fixes and mitigations required to address security issues. +Parity Technologies is committed to resolving security vulnerabilities in our +software quickly and carefully. We take the necessary steps to minimize risk, +provide timely information, and deliver vulnerability fixes and mitigations +required to address security issues. ## Reporting a Vulnerability -Security vulnerabilities in Parity software should be reported by email to security@parity.io. If you think your report might be eligible for the Parity Bug Bounty Program, your email should be sent to bugbounty@parity.io. +Security vulnerabilities in Parity software should be reported by email to +security@parity.io. If you think your report might be eligible for the Parity +Bug Bounty Program, your email should be sent to bugbounty@parity.io. Your report should include the following: @@ -15,33 +22,49 @@ Your report should include the following: - reproduction - other details -Try to include as much information in your report as you can, including a description of the vulnerability, its potential impact, and steps for reproducing it. Be sure to use a descriptive subject line. +Try to include as much information in your report as you can, including a +description of the vulnerability, its potential impact, and steps for +reproducing it. Be sure to use a descriptive subject line. -You'll receive a response to your email within two business days indicating the next steps in handling your report. We encourage finders to use encrypted communication channels to protect the confidentiality of vulnerability reports. You can encrypt your report using our public key. This key is [on MIT's key server](https://pgp.mit.edu/pks/lookup?op=get&search=0x5D0F03018D07DE73) server and reproduced below. +You'll receive a response to your email within two business days indicating +the next steps in handling your report. We encourage finders to use encrypted +communication channels to protect the confidentiality of vulnerability reports. +You can encrypt your report using our public key. This key is [on MIT's key server](https://pgp.mit.edu/pks/lookup?op=get&search=0x5D0F03018D07DE73) +server and reproduced below. -After the initial reply to your report, our team will endeavor to keep you informed of the progress being made towards a fix. These updates will be sent at least every five business days. +After the initial reply to your report, our team will endeavor to keep you +informed of the progress being made towards a fix. These updates will be sent +at least every five business days. Thank you for taking the time to responsibly disclose any vulnerabilities you find. ## Responsible Investigation and Reporting -Responsible investigation and reporting includes, but isn't limited to, the following: +Responsible investigation and reporting includes, but isn't limited to, the +following: - Don't violate the privacy of other users, destroy data, etc. -- Don’t defraud or harm Parity Technologies Ltd or its users during your research; you should make a good faith effort to not interrupt or degrade our services. -- Don't target our physical security measures, or attempt to use social engineering, spam, distributed denial of service (DDOS) attacks, etc. +- Don’t defraud or harm Parity Technologies Ltd or its users during your + research; you should make a good faith effort to not interrupt or degrade our + services. +- Don't target our physical security measures, or attempt to use social + engineering, spam, distributed denial of service (DDOS) attacks, etc. - Initially report the bug only to us and not to anyone else. -- Give us a reasonable amount of time to fix the bug before disclosing it to anyone else, and give us adequate written warning before disclosing it to anyone else. -- In general, please investigate and report bugs in a way that makes a reasonable, good faith effort not to be disruptive or harmful to us or our users. Otherwise your actions might be interpreted as an attack rather than an effort to be helpful. +- Give us a reasonable amount of time to fix the bug before disclosing it to + anyone else, and give us adequate written warning before disclosing it to + anyone else. +- In general, please investigate and report bugs in a way that makes a + reasonable, good faith effort not to be disruptive or harmful to us or our + users. Otherwise your actions might be interpreted as an attack rather than + an effort to be helpful. ## Bug Bounty Program -Our Bug Bounty Program allows us to recognise and reward members of the Parity community for helping us find and address significant bugs, in accordance with the terms of the Parity Bug Bounty Program. A detailed description on eligibility, rewards, legal information and terms & conditions for contributors can be found on [our website](https://paritytech.io/bug-bounty.html). - - - - - +Our Bug Bounty Program allows us to recognize and reward members of the Parity +community for helping us find and address significant bugs, in accordance with +the terms of the Parity Bug Bounty Program. A detailed description on +eligibility, rewards, legal information and terms & conditions for contributors +can be found on [our website](https://paritytech.io/bug-bounty.html). ## Plaintext PGP Key diff --git a/docs/STYLE_GUIDE.md b/docs/STYLE_GUIDE.md new file mode 100644 index 000000000000..eb3399880f53 --- /dev/null +++ b/docs/STYLE_GUIDE.md @@ -0,0 +1,180 @@ +--- +title: Style Guide for Rust in the Polkadot-SDK +--- + +Where possible these styles are enforced by settings in `rustfmt.toml` so if you run `cargo fmt` +then you will adhere to most of these style guidelines automatically. + +# Formatting + +- Indent using tabs. +- Lines should be longer than 100 characters long only in exceptional circumstances and certainly + no longer than 120. For this purpose, tabs are considered 4 characters wide. +- Indent levels should be greater than 5 only in exceptional circumstances and certainly no + greater than 8. If they are greater than 5, then consider using `let` or auxiliary functions in + order to strip out complex inline expressions. +- Never have spaces on a line prior to a non-whitespace character +- Follow-on lines are only ever a single indent from the original line. + +```rust +fn calculation(some_long_variable_a: i8, some_long_variable_b: i8) -> bool { + let x = some_long_variable_a * some_long_variable_b + - some_long_variable_b / some_long_variable_a + + sqrt(some_long_variable_a) - sqrt(some_long_variable_b); + x > 10 +} +``` + +- Indent level should follow open parens/brackets, but should be collapsed to the smallest number + of levels actually used: + +```rust +fn calculate( + some_long_variable_a: f32, + some_long_variable_b: f32, + some_long_variable_c: f32, +) -> f32 { + (-some_long_variable_b + sqrt( + // two parens open, but since we open & close them both on the + // same line, only one indent level is used + some_long_variable_b * some_long_variable_b + - 4 * some_long_variable_a * some_long_variable_c + // both closed here at beginning of line, so back to the original indent + // level + )) / (2 * some_long_variable_a) +} +``` + +- `where` is indented, and its items are indented one further. +- Argument lists or function invocations that are too long to fit on one line are indented + similarly to code blocks, and once one param is indented in such a way, all others should be, + too. Run-on parameter lists are also acceptable for single-line run-ons of basic function calls. + +```rust +// OK +fn foo( + really_long_parameter_name_1: SomeLongTypeName, + really_long_parameter_name_2: SomeLongTypeName, + shrt_nm_1: u8, + shrt_nm_2: u8, +) { + ... +} + +// NOT OK +fn foo(really_long_parameter_name_1: SomeLongTypeName, really_long_parameter_name_2: SomeLongTypeName, + shrt_nm_1: u8, shrt_nm_2: u8) { + ... +} +``` + +```rust +{ + // Complex line (not just a function call, also a let statement). Full + // structure. + let (a, b) = bar( + really_long_parameter_name_1, + really_long_parameter_name_2, + shrt_nm_1, + shrt_nm_2, + ); + + // Long, simple function call. + waz( + really_long_parameter_name_1, + really_long_parameter_name_2, + shrt_nm_1, + shrt_nm_2, + ); + + // Short function call. Inline. + baz(a, b); +} +``` + +- Always end last item of a multi-line comma-delimited set with `,` when legal: + +```rust +struct Point { + x: T, + y: T, // <-- Multiline comma-delimited lists end with a trailing , +} + +// Single line comma-delimited items do not have a trailing `,` +enum Meal { Breakfast, Lunch, Dinner }; +``` + +- Avoid trailing `;`s where unneeded. + +```rust +if condition { + return 1 // <-- no ; here +} +``` + +- `match` arms may be either blocks or have a trailing `,` but not both. +- Blocks should not be used unnecessarily. + +```rust +match meal { + Meal::Breakfast => "eggs", + Meal::Lunch => { check_diet(); recipe() }, +// Meal::Dinner => { return Err("Fasting") } // WRONG + Meal::Dinner => return Err("Fasting"), +} +``` + +# Style + +- Panickers require explicit proofs they don't trigger. Calling `unwrap` is discouraged. The + exception to this rule is test code. Avoiding panickers by restructuring code is preferred if + feasible. + +```rust +let mut target_path = + self.path().expect( + "self is instance of DiskDirectory;\ + DiskDirectory always returns path;\ + qed" + ); +``` + +- Unsafe code requires explicit proofs just as panickers do. When introducing unsafe code, + consider trade-offs between efficiency on one hand and reliability, maintenance costs, and + security on the other. Here is a list of questions that may help evaluating the trade-off while + preparing or reviewing a PR: + - how much more performant or compact the resulting code will be using unsafe code, + - how likely is it that invariants could be violated, + - are issues stemming from the use of unsafe code caught by existing tests/tooling, + - what are the consequences if the problems slip into production. + +# Manifest Formatting + +> **TLDR** +> You can use the CLI tool [Zepter](https://crates.io/crates/zepter) to +> format the files: `zepter format features` + +Rust `Cargo.toml` files need to respect certain formatting rules. All entries +need to be alphabetically sorted. This makes it easier to read them and insert +new entries. The exhaustive list of rules is enforced by the CI. The general +format looks like this: + +- The feature is written as a single line if it fits within 80 chars: + +```toml +[features] +default = [ "std" ] +``` + +- Otherwise the feature is broken down into multiple lines with one entry per + line. Each line is padded with one tab and no trailing spaces but a trailing + comma. + +```toml +[features] +default = [ + "loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong", + # Comments go here as well ;) + "std", +] +``` \ No newline at end of file diff --git a/polkadot/CODE_OF_CONDUCT.md b/polkadot/CODE_OF_CONDUCT.md deleted file mode 100644 index 400c9b3901e2..000000000000 --- a/polkadot/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,52 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a professional setting - -### Facilitation, Not Strongarming - -We recognise that this software is merely a tool for users to create and maintain their blockchain of preference. We see that blockchains are naturally community platforms with users being the ultimate decision makers. We assert that good software will maximise user agency by facilitate user-expression on the network. As such: - -* This project will strive to give users as much choice as is both reasonable and possible over what protocol they adhere to; but -* use of the project's technical forums, commenting systems, pull requests and issue trackers as a means to express individual protocol preferences is forbidden. - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at . The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at https://contributor-covenant.org/version/1/4 - -[homepage]: https://contributor-covenant.org diff --git a/polkadot/CONTRIBUTING.md b/polkadot/CONTRIBUTING.md deleted file mode 100644 index d82b80bd8d2e..000000000000 --- a/polkadot/CONTRIBUTING.md +++ /dev/null @@ -1,46 +0,0 @@ -# Contributing - -## Rules - -There are a few basic ground-rules for contributors (including the maintainer(s) of the project): - -- **No `--force` pushes** or modifying the Git 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 [house coding style](https://github.com/paritytech/substrate/blob/master/docs/STYLE_GUIDE.md). - -### Merging pull requests once CI is successful - -- A pull request that does not alter any logic (e.g. comments, dependencies, docs) may be tagged [`insubstantial`](https://github.com/paritytech/polkadot/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3AA2-insubstantial) and merged by its author. -- A pull request with no large change to logic that is an urgent fix may be merged after a non-author contributor has reviewed it well. -- All other PRs should sit for 48 hours with the [`pleasereview`](https://github.com/paritytech/polkadot/pulls?q=is:pr+is:open+label:A0-pleasereview) tag in order to garner feedback. -- No PR should be merged until all reviews' comments are addressed. - -### 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. - -## 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: diff --git a/substrate/docs/CODE_OF_CONDUCT.md b/substrate/docs/CODE_OF_CONDUCT.md deleted file mode 100644 index 400c9b3901e2..000000000000 --- a/substrate/docs/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,52 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a professional setting - -### Facilitation, Not Strongarming - -We recognise that this software is merely a tool for users to create and maintain their blockchain of preference. We see that blockchains are naturally community platforms with users being the ultimate decision makers. We assert that good software will maximise user agency by facilitate user-expression on the network. As such: - -* This project will strive to give users as much choice as is both reasonable and possible over what protocol they adhere to; but -* use of the project's technical forums, commenting systems, pull requests and issue trackers as a means to express individual protocol preferences is forbidden. - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at . The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at https://contributor-covenant.org/version/1/4 - -[homepage]: https://contributor-covenant.org diff --git a/substrate/docs/CONTRIBUTING.md b/substrate/docs/CONTRIBUTING.md deleted file mode 100644 index cbaf6206e78f..000000000000 --- a/substrate/docs/CONTRIBUTING.md +++ /dev/null @@ -1,134 +0,0 @@ -# Contributing - -The `Substrate` project is an ***OPENISH Open Source Project*** - -Contributors are invited to our `#frame-contributors` channel on the Polkadot Discord for support and coordination: -[![Discord](https://img.shields.io/discord/722223075629727774?style=for-the-badge&logo=discord&label=Discord)](https://dot.li/discord) - -## 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](STYLE_GUIDE.md). -6. Contributors should adhere to the [house documenting style](DOCUMENTATION_GUIDELINES.md), when applicable. - -## 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`](https://github.com/paritytech/substrate/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3AA2-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:** - -1. Please tag each PR with exactly one `A`, `B`, `C` and `D` label at the minimum. -2. When tagging a PR, it should be done while keeping all downstream users in mind. Downstream users are not just Polkadot or system parachains, but also all the other parachains and solo chains that are using Substrate. The labels are used by downstream users to track changes and to include these changes properly into their own releases. -3. Once a PR is ready for review please add the [`A0-please_review`](https://github.com/paritytech/substrate/pulls?q=is%3Apr+is%3Aopen+label%3AA0-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. -4. 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. [`A3-in_progress`](https://github.com/paritytech/substrate/labels/A3-in_progress) is a general indicator that the PR is work in progress. -5. PRs must be tagged with `B*` labels to signal if a change is note worthy for downstream users. The respective `T*` labels should be added to signal the component that was changed. `B0-silent` must only be used for changes that don’t require any attention by downstream users. -6. PRs must be tagged with their release importance via the `C1-C7` labels. The release importance is only informing about how important it is to apply a release that contains the change. -7. PRs must be tagged with their audit requirements via the `D1-D9` labels. -8. PRs that introduce runtime migrations must be tagged with [`E0-runtime_migration`](https://github.com/paritytech/substrate/labels/E0-runtime_migration). See the [Migration Best Practices here](https://github.com/paritytech/substrate/blob/master/utils/frame/try-runtime/cli/src/lib.rs#L18) for more info about how to test runtime migrations. -9. PRs that introduce irreversible database migrations must be tagged with [`E1-database_migration`](https://github.com/paritytech/substrate/labels/E1-database_migration). -10. PRs that add host functions must be tagged with with [`E3-host_functions`](https://github.com/paritytech/substrate/labels/E3-host_functions). -11. PRs that break the external API must be tagged with [`F3-breaks_API`](https://github.com/paritytech/substrate/labels/F3-breaks_API). -12. PRs that change the mechanism for block authoring in a backwards-incompatible way must be tagged with [`F1-breaks_authoring`](https://github.com/paritytech/substrate/labels/F1-breaks_authoring). -13. PRs that "break everything" must be tagged with [`F0-breaks_everything`](https://github.com/paritytech/substrate/labels/F0-breaks_everything). -14. PRs should be categorized into projects. -15. No PR should be merged until all reviews' comments are addressed and CI is successful. - -**Noting relevant changes:** - -When breaking APIs, it should be mentioned on what was changed in the PR description alongside some examples on how to change the code to make it work/compile. - -The PR description should also mention potential storage migrations and if they require some special setup aside adding it to the list of migrations in the runtime. - -**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 against 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. (effectively 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 [`E6-needs_polkadot_pr`](https://github.com/paritytech/substrate/labels/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 [labels](https://paritytech.github.io/labels/doc_substrate.html) to manage PRs and issues and communicate state of a PR. Please familiarize yourself with them. The best way to get started is to a pick a ticket tagged [`easy`](https://github.com/paritytech/substrate/issues?q=is%3Aissue+is%3Aopen+label%3AZ1-easy) or [`medium`](https://github.com/paritytech/substrate/issues?q=is%3Aissue+is%3Aopen+label%3AZ2-medium) and get going or [`mentor`](https://github.com/paritytech/substrate/issues?q=is%3Aissue+is%3Aopen+label%3AZ6-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-**` or `J-**` Issue severity and type. EXACTLY ONE REQUIRED. -2. `U-*` Issue urgency, suggesting in what time manner does this issue need to be resolved. AT MOST ONE ALLOWED. -3. `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 output 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