mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-04-25 22:17:58 +00:00
Move developer-hub to polkadot-sdk-docs (#2598)
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:
@@ -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.
|
||||
Reference in New Issue
Block a user