Skip to content

Latest commit

 

History

History
71 lines (46 loc) · 2.92 KB

prdoc.md

File metadata and controls

71 lines (46 loc) · 2.92 KB
Raw

PRDoc

Intro

With the merge of PR #1946, a new method for documenting changes has been introduced: prdoc. The prdoc repository 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 of the repository
  • compliant with the JSON schema 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:

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