pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-06-21 21:31:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Move developer-hub to polkadot-sdk-docs (#2598)

Browse Source 
This PR is a continuation of
https://github.com/paritytech/polkadot-sdk/pull/2102 and part of an
initiative started here https://hackmd.io/@romanp/rJ318ZCEp
What has been done:
- The content under `docs/*` (with the exception of `docs/mermaid`) has
been moved to `docs/contributor/`
- Developer Hub has been renamed to Polkadot SDK Docs, and the crate has
been renamed from `developer-hub` to `polkadot-sdk-docs`
- The content under `developer-hub/*` has been moved to `docs/sdk`

---
Original PR https://github.com/paritytech/polkadot-sdk/pull/2565, it has
been close due to too many rebase conflicts

---------

Co-authored-by: Serban Iorga <serban@parity.io>
Co-authored-by: Chevdor <chevdor@users.noreply.github.com>
Co-authored-by: Egor_P <egor@parity.io>
Co-authored-by: Bastian Köcher <git@kchr.de>
This commit is contained in:
Juan Girini
2023-12-05 10:23:24 +01:00
committed by GitHub
parent 2f9af7873d
commit a310df263d
67 changed files with 153 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contributor/CODE_OF_CONDUCT.md
+76
View File
@@ -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 <admin@parity.io>. 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
docs/contributor/CONTRIBUTING.md
+154
View File
@@ -0,0 +1,154 @@
# 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](https://paritytech.github.io/labels/doc_polkadot-sdk.html).
### 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 you’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:
1. if a changelog is necessary and attached
1. the quality of information in the changelog file
1. the PR has an impact on docs
1. 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.
## Documentation
All Pull Requests must contain proper title & description.
Some Pull Requests can be exempt of `prdoc` documentation, those must be labelled with
[`R0-silent`](https://github.com/paritytech/labels/blob/main/ruled_labels/specs_polkadot-sdk.yaml#L89-L91).
Non "silent" PRs must come with documentation in the form of a `.prdoc` file.
See more about `prdoc` [here](./prdoc.md)
## 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. Alternatively, look out for issues tagged [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 output there is a script
- `./scripts/update-ui-tests.sh` to update the tests for a current rust version locally
- `./scripts/update-ui-tests.sh 1.70` # to update the tests for a specific rust version locally
Or if you have opened PR and you're member of `paritytech` - you can use command-bot to run the tests for you in CI:
- `bot update-ui` - will run the tests for the current rust version
- `bot update-ui latest --rust_version=1.70.0` - will run the tests for the specified rust version
- `bot update-ui latest -v CMD_IMAGE=paritytech/ci-unified:bullseye-1.70.0-2023-05-23 --rust_version=1.70.0` -
will run the tests for the specified rust version and specified image
## Feature Propagation
We use [zepter](https://github.com/ggwpez/zepter) to enforce features are propagated between crates correctly.
## Command Bot
If you're member of **paritytech** org - you can use command-bot to run various of common commands in CI:
Start with comment in PR: `bot help` to see the list of available commands.
docs/contributor/DEPRECATION_CHECKLIST.md
+79
View File
@@ -0,0 +1,79 @@
# Deprecation Checklist
This deprecation checklist makes sense while we don’t use [SemVer](https://semver.org/).
After that, this document will most likely change.
As deprecation and removal of existing code can happen on any release, we need to be mindful that external builders
could be impacted by the changes we make.
The deprecation checklist tries to mitigate this impact, while still keeping the developer experience, the DevEx, as
smooth as possible.
To start a deprecation process, a new issue with the label `T15-deprecation` needs to be created for correct tracking.
Then these are the actions to take:
## Hard deprecate by adding a warning message
The warning message shall include a removal month and year, which is suggested to be 6 months after the deprecation
notice is released.
This means that the code will be removed in a release within that month (or after, but never before). Please use this
template, doing so makes it easy to search through the code base:
```rust
#[deprecated(note = "[DEPRECATED] will be removed after [DATE]. [ALTERNATIVE]")]
```
`[ALTERNATIVE]` won't always be possible but offer it if it is.
E.g.
```rust
#[deprecated(note = "`GenesisConfig` will be removed after December 2023. Use `RuntimeGenesisConfig` instead.")]
```
Some pieces of code cannot be labeled as deprecated, like [reexports](https://github.com/rust-lang/rust/issues/30827)
or [dispatchables](https://github.com/paritytech/polkadot-sdk/issues/182#issuecomment-1691684159), for instance.
In cases like that we can only make a visible enough comment, and make sure that we [announce the deprecation properly](#announce-the-deprecation-and-removal).
## Remove usage of the deprecated code in the code base
Just make sure that we are not using the deprecated code ourselves.
If you added the deprecation warning from the previous step, this can be done by making sure that warning is not shown
when building the code.
## Update examples and tutorials
Make sure that the rust docs are updated.
We also need [https://docs.substrate.io/](https://docs.substrate.io/) to be updated accordingly. The repo behind it is
[https://github.com/substrate-developer-hub/substrate-docs](https://github.com/substrate-developer-hub/substrate-docs).
## Announce the deprecation and removal
**At minimum they should be noted in the release log.** Please see how to document a PR [here](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CONTRIBUTING.md#documentation).
There you can give instructions based on the audience and tell them what they need to do to upgrade the code.
Some breaking changes have a bigger impact than others. When the impact is big the release note is not enough, though
it should still be the primary place for the notice. You can link back to the changelog files in other channels if you
want to announce it somewhere else.
Make sure you are as loud as you need to be for the magnitude of the breaking change.
## Removal version is planned
Depending on the removal date indicated in the deprecation warning in the [first step](#hard-deprecate-by-adding-a-warning-message),
the nature and the importance of the change, it might make sense to coordinate the release with other developers and
with the Release team.
## Deprecated code is removed
The deprecated code finally gets removed.
Don’t forget to [announce this accordingly](#announce-the-deprecation-and-removal).
✅ In order to not forget any of these steps, consider using this template in your deprecation issue:
```markdown
### Tasks
- [ ] Deprecate code by adding a warning message
- [ ] Remove usage of the deprecated code in the code base
- [ ] Update examples and tutorials
- [ ] Announce code deprecation
- [ ] Plan removal version
- [ ] Announce code removal
- [ ] Remove deprecated code
```
docs/contributor/DOCUMENTATION_GUIDELINES.md
+355
View File
@@ -0,0 +1,355 @@
# Substrate Documentation Guidelines
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 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)
- [What to Document?](#what-to-document)
- [Rust Docs vs. Code Comments](#rust-docs-vs-code-comments)
- [How to Document?](#how-to-document)
- [TLDR](#tldr)
- [Proc-Macros](#proc-macros)
- [Other Guidelines](#other-guidelines)
- [Document Through Code](#document-through-code)
- [Formatting Matters](#formatting-matters)
- [Pallet Crates](#pallet-crates)
- [Top Level Pallet Docs (`lib.rs`)](#top-level-pallet-docs-librs)
- [Polkadot and Substrate](#polkadot-and-substrate)
- [Dispatchables](#dispatchables)
- [Storage Items](#storage-items)
- [Errors and Events](#errors-and-events)
---
## General/Non-Pallet Crates
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 this filter:
1. In the crates assigned to `docs-audit` in [CODEOWNERS](./CODEOWNERS),
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.
```rust
/// Computes the square root of the input, returning `Ok(_)` if successful.
///
/// # Errors
/// ...
///
// Details about the complexity, how you implemented this, and some quirks that
// are NOT relevant to the external interface, so it starts with '//'.
// This can also be moved inside the function.
pub fn sqrt(x: u32) -> Result<u32, ()> {
todo!();
}
```
---
### How to Document?
There are good sources to look into:
- [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 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_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.
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.
---
#### 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).
---
### Other Guidelines
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:
---
#### 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.
- 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
/// 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.
---
#### Formatting Matters
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
/// we optimize the other variant of it, we would be able to achieve more
/// efficiency but I have to think about it. Probably can panic if the input
/// overflows u32.
fn multiply_by_2(x: u32) -> u32 { .. }
```
```rust
/// Multiplies an input of type [`u32`] by two.
///
/// # Panics
///
/// Panics if the input overflows.
///
/// # Complexity
///
/// Is implemented using some algorithm that yields complexity of O(1).
// 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.
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 following is relevant to how to document parts of a crate that is a pallet. See
[`pallet-fast-unstake`](../substrate/frame/fast-unstake/src/lib.rs) as one example of adhering these guidelines.
---
### Top Level Pallet Docs (`lib.rs`)
For the top-level pallet docs, consider the following template:
```
//! # <Pallet Name>
//!
//! <single-liner about the pallet>.
//!
//! ## Pallet API
//!
//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated. There is no need to repeat
//! things like "See Config trait for ...", which are generated inside [`pallet`] here anyways. You can use the line below as-is:>
//!
//! See the [`pallet`] module for more information about the interfaces this pallet exposes, including its
//! configuration trait, dispatchables, storage items, events and errors.
//!
//! ## Overview
//!
//! <should be high-level details that are relevant to the most broad audience>
//!
//! <The audience here is potentially non-coders who just want to know what this pallet does, not how it does it>
//!
//! <potentially a few paragraphs, focus on what external folks should know about the pallet>
//!
//! ### Example
//!
//! <Your pallet must have a few tests that cover important user journeys. Use https://crates.io/crates/docify to
//! reuse these as examples.>
//!
//! <The audience of this is those who want to know how this pallet works, to the extent of being able to build
//! something on top of it, like a DApp or another pallet. In some cases, you might want to add an example of how to
//! use this pallet in other pallets.>
//!
//! This section can most often be left as-is.
//!
//! ## Low Level / Implementation Details
//!
//! <The format of this section is up to you, but we suggest the Design-oriented approach that follows>
//!
//! <The audience of this would be your future self, or anyone who wants to gain a deep understanding of how the pallet
//! works so that they can eventually propose optimizations to it>
//!
//! ### Design Goals (optional)
//!
//! <Describe your goals with the pallet design.>
//!
//! ### Design (optional)
//!
//! <Describe how you've reached those goals. This should describe the storage layout of your pallet and what was your
//! approach in designing it that way.>
//!
//! ### Terminology (optional)
//!
//! <Optionally, explain any non-obvious terminology here. You can link to it if you want to use the terminology further
//! up>
```
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.
---
#### Polkadot and Substrate
Optionally, in order to demonstrate the relation between the two, you can start the pallet documentation with:
```
//! > Made with *Substrate*, for *Polkadot*.
//!
//! [![github]](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/fast-unstake) -
//! [![polkadot]](https://polkadot.network)
//!
//! [polkadot]: https://img.shields.io/badge/polkadot-E6007A?style=for-the-badge&logo=polkadot&logoColor=white
//! [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:
```
/// <One-liner explaining what the dispatchable does>
///
/// ## Dispatch Origin
///
/// The dispatch origin of this call must be <details (e.g. Root, Signed, Unsigned)>
///
/// ## Details
///
/// <All other details, namely any errors that could occur within this dispatch and the events this dispatch could emit>
///
/// ## Errors (optional)
///
/// <If an extensive list of errors can be returned, list them individually instead of mentioning them in the section
/// above>
///
/// ## Events (optional)
///
/// <Events are akin to the "return type" of dispatchables, optionally mention them>
pub fn name_of_dispatchable(origin: OriginFor<T>, ...) -> 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.
---
### 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.
Specifically for `error`, explain why the error has happened, and what can be done in order to avoid it.
## Documenting Changes/PR
See [PRDoc](./prdoc.md).
docs/contributor/PULL_REQUEST_TEMPLATE.md
+37
View File
@@ -0,0 +1,37 @@
✄ -----------------------------------------------------------------------------
Thank you for your Pull Request! 🙏 Please make sure it follows the contribution guidelines outlined in
[this document](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/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
*Please include a summary of the changes and the related issue. Please also include relevant motivation and context,
including:*
- What does this PR do?
- Why are these changes needed?
- How were these changes implemented and what do they affect?
*Use [Github semantic
linking](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
to address any open issues this PR relates to or closes.*
Fixes # (issue number, *if applicable*)
Closes # (issue number, *if applicable*)
# Checklist
- [ ] My PR includes a detailed description as outlined in the "Description" section above
- [ ] 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)
You can remove the "Checklist" section once all have been checked. Thank you for your contribution!
✄ -----------------------------------------------------------------------------
docs/contributor/SECURITY.md
+124
View File
@@ -0,0 +1,124 @@
<!-- markdown-link-check-disable -->
# 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.
## 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.
Your report should include the following:
- your name
- description of the vulnerability
- attack scenario (if any)
- components
- 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.
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.
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:
- 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.
- 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.
## Bug Bounty Program
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
```
-----BEGIN PGP PUBLIC KEY BLOCK-----
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
BZYiIhW7GG4ozvKDqyNm4eg=
=yKcB
-----END PGP PUBLIC KEY BLOCK-----
```
docs/contributor/STYLE_GUIDE.md
+164
View File
@@ -0,0 +1,164 @@
---
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 +nightly fmt`
then you will adhere to most of these style guidelines automatically.
To see exactly which nightly version is used, check our CI job logs.
# 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<T> {
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
We use [taplo](https://taplo.tamasfe.dev/) to enforce consistent TOML formatting.
You can install it with `cargo install taplo-cli` and format your code with `taplo format --config .config/taplo.toml`.
See the config file for the exact rules.
You may find useful
- [Taplo VSCode extension](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)
- For NeoVim, [taplo is avaliable with Mason](https://github.com/williamboman/mason-lspconfig.nvim#available-lsp-servers)
docs/contributor/container.md
+66
View File
@@ -0,0 +1,66 @@
# Using Containers
Using containers via **Podman** or **Docker** brings benefit, whether it is to build a container image or run a node
while keeping a minimum footprint on your local system.
This document mentions using `podman` or `docker`. Those are usually interchangeable and it is encouraged using
preferably **Podman**. If you have podman installed and want to use all the commands mentioned below, you can simply
create an alias with `alias docker=podman`.
There are a few options to build a node within a container and inject a binary inside an image.
## Parity built container image
Parity builds and publishes a container image that can be found as `docker.io/parity/polkadot-parachain`.
## Parity CI image
Parity maintains and uses internally a generic "CI" image that can be used as a base to build binaries: [Parity CI
container image](https://github.com/paritytech/scripts/tree/master/dockerfiles/ci-linux):
The command below allows building a Linux binary without having to even install Rust or any dependency locally:
```bash
docker run --rm -it \
-w /polkadot-sdk \
-v $(pwd):/polkadot-sdk \
paritytech/ci-linux:production \
cargo build --release --locked -p polkadot-parachain-bin --bin polkadot-parachain
sudo chown -R $(id -u):$(id -g) target/
```
If you want to reproduce other steps of CI process you can use the following
[guide](https://github.com/paritytech/scripts#gitlab-ci-for-building-docker-images).
## Injected image
Injecting a binary inside a base image is the quickest option to get a working container image. This only works if you
were able to build a Linux binary, either locally, or using a container as described above.
After building a Linux binary (`polkadot-parachain`) with cargo or with Parity CI image as documented above, the
following command allows producing a new container image where the compiled binary is injected:
```bash
ARTIFACTS_FOLDER=./target/release /docker/scripts/build-injected.sh
```
## Container build
Alternatively, you can build an image with a builder pattern. This options takes a while but offers a simple method for
anyone to get a working container image without requiring any of the Rust toolchain installed locally.
```bash
docker build \
--tag $OWNER/$IMAGE_NAME \
--file ./docker/dockerfiles/polkadot-parachain/polkadot-parachain_builder.Dockerfile .
```
You may then run your new container:
```bash
docker run --rm -it \
$OWNER/$IMAGE_NAME \
--collator --tmp \
--execution wasm \
--chain /specs/asset-hub-westend.json
```
docs/contributor/docker.md
+173
View File
@@ -0,0 +1,173 @@
# Using Containers
The following commands should work no matter if you use Docker or Podman. In general, Podman is recommended. All
commands are "engine neutral" so you can use the container engine of your choice while still being able to copy/paste
the commands below.
Let's start defining Podman as our engine:
```
ENGINE=podman
```
If you prefer to stick with Docker, use:
```
ENGINE=docker
```
## The easiest way
The easiest/faster option to run Polkadot in Docker is to use the latest release images. These are small images that use
the latest official release of the Polkadot binary, pulled from our Debian package.
**_The following examples are running on westend chain and without SSL. They can be used to quick start and learn how
Polkadot needs to be configured. Please find out how to secure your node, if you want to operate it on the internet. Do
not expose RPC and WS ports, if they are not correctly configured._**
Let's first check the version we have. The first time you run this command, the Polkadot docker image will be
downloaded. This takes a bit of time and bandwidth, be patient:
```bash
$ENGINE run --rm -it parity/polkadot:latest --version
```
You can also pass any argument/flag that Polkadot supports:
```bash
$ENGINE run --rm -it parity/polkadot:latest --chain westend --name "PolkaDocker"
```
## Examples
Once you are done experimenting and picking the best node name :) you can start Polkadot as daemon, exposes the Polkadot
ports and mount a volume that will keep your blockchain data locally. Make sure that you set the ownership of your local
directory to the Polkadot user that is used by the container.
Set user id 1000 and group id 1000, by running `chown 1000.1000 /my/local/folder -R` if you use a bind mount.
To start a Polkadot node on default rpc port 9933 and default p2p port 30333 use the following command. If you want to
connect to rpc port 9933, then must add Polkadot startup parameter: `--rpc-external`.
```bash
$ENGINE run -d -p 30333:30333 -p 9933:9933 \
-v /my/local/folder:/polkadot \
parity/polkadot:latest \
--chain westend --rpc-external --rpc-cors all \
--name "PolkaDocker
```
If you also want to expose the webservice port 9944 use the following command:
```bash
$ENGINE run -d -p 30333:30333 -p 9933:9933 -p 9944:9944 \
-v /my/local/folder:/polkadot \
parity/polkadot:latest \
--chain westend --ws-external --rpc-external --rpc-cors all --name "PolkaDocker"
```
## Using Docker compose
You can use the following docker-compose.yml file:
```bash
version: '2'
services:
polkadot:
container_name: polkadot
image: parity/polkadot
ports:
- 30333:30333 # p2p port
- 9933:9933 # rpc port
- 9944:9944 # ws port
- 9615:9615 # Prometheus port
volumes:
- /my/local/folder:/polkadot
command: [
"--name", "PolkaDocker",
"--ws-external",
"--rpc-external",
"--prometheus-external",
"--rpc-cors", "all"
]
```
With following `docker-compose.yml` you can set up a node and use `polkadot-js-apps` as the front end on port 80. After
starting the node use a browser and enter your Docker host IP in the URL field: _<http://[YOUR_DOCKER_HOST_IP]>_
```bash
version: '2'
services:
polkadot:
container_name: polkadot
image: parity/polkadot
ports:
- 30333:30333 # p2p port
- 9933:9933 # rpc port
- 9944:9944 # ws port
- 9615:9615 # Prometheus port
command: [
"--name", "PolkaDocker",
"--ws-external",
"--rpc-external",
"--prometheus-external",
"--rpc-cors", "all"
]
polkadotui:
container_name: polkadotui
image: jacogr/polkadot-js-apps
environment:
- WS_URL=ws://[YOUR_DOCKER_HOST_IP]:9944
ports:
- 80:80
```
## Limiting Resources
Chain syncing will utilize all available memory and CPU power your server has to offer, which can lead to crashing.
If running on a low resource VPS, use `--memory` and `--cpus` to limit the resources used. E.g. To allow a maximum of
512MB memory and 50% of 1 CPU, use `--cpus=".5" --memory="512m"`. Read more about limiting a container's resources
[here](https://docs.docker.com/config/containers/resource_constraints).
## Build your own image
There are 3 options to build a Polkadot container image:
- using the builder image
- using the injected "Debian" image
- using the generic injected image
### Builder image
To get up and running with the smallest footprint on your system, you may use an existing Polkadot Container image.
You may also build a Polkadot container image yourself (it takes a while...) using the container specs
`docker/dockerfiles/polkadot/polkadot_builder.Dockerfile`.
### Debian injected
The Debian injected image is how the official Polkadot container image is produced. It relies on the Debian package that
is published upon each release. The Debian injected image is usually available a few minutes after a new release is
published. It has the benefit of relying on the GPG signatures embedded in the Debian package.
### Generic injected
For simple testing purposes, the easiest option for Polkadot and also random binaries, is to use the
`binary_injected.Dockerfile` container spec. This option is less secure since the injected binary is not checked at all
but it has the benefit to be simple. This option requires to already have a valid `polkadot` binary, compiled for Linux.
This binary is then simply copied inside the `parity/base-bin` image.
## Reporting issues
If you run into issues with Polkadot when using docker, please run the following command (replace the tag with the
appropriate one if you do not use latest):
```bash
$ENGINE run --rm -it parity/polkadot:latest --version
```
This will show you the Polkadot version as well as the git commit ref that was used to build your container. You can now
paste the version information in a [new issue](https://github.com/paritytech/polkadot/issues/new/choose).
docs/contributor/markdown_linting.md
+20
View File
@@ -0,0 +1,20 @@
# Markdown linting
Since the introduction of [PR #1309](https://github.com/paritytech/polkadot-sdk/pull/1309), the markdown
files in this repository are checked by a linter for formatting and consistency.
The linter used is [`markdownlint`](https://github.com/DavidAnson/markdownlint) and can be installed locally on your
machine. It can also be setup as [pre-commit hook](https://github.com/igorshubovych/markdownlint-cli#use-with-pre-commit)
to ensure that your markdown is passing all the tests.
The rules in place are defined
[here](https://github.com/paritytech/polkadot-sdk/blob/master/.github/.markdownlint.yaml).
You may run `markdownlint` locally using:
```
markdownlint --config .github/.markdownlint.yaml --ignore target .
```
There are also plugins for your favorite editor, that can ensure that most
of the rules will pass and fix typical issues (such as trailing spaces,
missing eof new line, long lines, etc...)
docs/contributor/prdoc.md
+71
View File
@@ -0,0 +1,71 @@
# PRDoc
## Intro
With the merge of [PR #1946](https://github.com/paritytech/polkadot-sdk/pull/1946), a new method for
documenting changes has been introduced: `prdoc`. The [prdoc repository](https://github.com/paritytech/prdoc)
contains more documentation and tooling.
The current document describes how to quickly get started authoring `PRDoc` files.
## Requirements
When creating a PR, the author needs to decides with the `R0` label whether the change (PR) should
appear in the release notes or not.
Labelling a PR with `R0` means that no `PRDoc` is required.
A PR without the `R0` label **does** require a valid `PRDoc` file to be introduced in the PR.
## PRDoc how-to
A `.prdoc` file is a YAML file with a defined structure (ie JSON Schema).
For significant changes, a `.prdoc` file is mandatory and the file must meet the following
requirements:
- file named `pr_NNNN.prdoc` where `NNNN` is the PR number.
For convenience, those file can also contain a short description: `pr_NNNN_foobar.prdoc`.
- located under the [`prdoc` folder](https://github.com/paritytech/polkadot-sdk/tree/master/prdoc) of the repository
- compliant with the [JSON schema](https://json-schema.org/) defined in `prdoc/schema_user.json`
Those requirements can be fulfilled manually without any tooling but a text editor.
## Tooling
Users might find the following helpers convenient:
- Setup VSCode to be aware of the prdoc schema: see [using VSCode](https://github.com/paritytech/prdoc#using-vscode)
- Using the `prdoc` cli to:
- generate a `PRDoc` file from a [template defined in the Polkadot SDK
repo](https://github.com/paritytech/polkadot-sdk/blob/master/prdoc/.template.prdoc) simply providing a PR number
- check the validity of one or more `PRDoc` files
## `prdoc` cli usage
The `prdoc` cli documentation can be found at https://github.com/paritytech/prdoc#prdoc
tldr:
- `prdoc generate <NNNN>`
- `prdoc check -n <NNNN>`
where <NNNN> is the PR number.
## Pick an audience
While describing a PR, the author needs to consider which audience(s) need to be addressed.
The list of valid audiences is described and documented in the JSON schema as follow:
- `Node Dev`: Those who build around the client side code. Alternative client builders, SMOLDOT, those who consume RPCs.
These are people who are oblivious to the runtime changes. They only care about the meta-protocol, not the protocol
itself.
- `Runtime Dev`: All of those who rely on the runtime. A parachain team that is using a pallet. A DApp that is using a
pallet. These are people who care about the protocol (WASM), not the meta-protocol (client).
- `Node Operator`: Those who don't write any code and only run code.
- `Runtime User`: Anyone using the runtime. This can be a token holder or a dev writing a front end for a chain.
## Tips
The PRDoc schema is defined in each repo and usually is quite restrictive.
You cannot simply add a new property to a `PRDoc` file unless the Schema allows it.