RFC: generated CHANGELOG.md from conventional-commit PR titles

Follow-up: https://github.com/paritytech/web3-storage/pull/318#pullrequestreview-4971097984

Motivation

Current repository ships releases with no human-authored record of what changed.

A provider operator upgrading from v0.4.0-paseo to v0.4.1-paseo wants to know whether the upgrade changes the HTTP API, requires a config change, or carries a runtime migration.
What they get instead is RELEASE_NOTES.md as generated by .github/workflows/release.yml (the "Add runtime info to changelog" step), which is 100% machine-generated:

• srtool build info and compiler version
• runtime size, compression ratio, core version, metadata version
• Blake2-256 and IPFS hashes
• a sha256 table for the provider-node binaries

Every line of that is an artifact fingerprint. Not one line says what changed.

Proposed Design

Mirror polkadot-sdk's setup component for component. Every piece below already exists upstream and is being ported, not invented.

1. prdoc/ directory and config

.prdoc.toml
prdoc/
  .gitkeep
  .template.prdoc
  schema_user.json
  pr_360.prdoc            # unreleased, one per PR
  v0.5.0-paseo/           # archived at release
    pr_352.prdoc

.prdoc.toml, copied verbatim from upstream except the paths:

# Config file for prdoc, see https://github.com/paritytech/prdoc
version = 1
schema = "prdoc/schema_user.json"
output_dir = "prdoc"
prdoc_folders = ["prdoc"]
template = "prdoc/.template.prdoc"

2. The per-PR file

Same schema as upstream. title, doc[] with an audience and a description, and crates[] with a semver bump:

# prdoc/pr_339.prdoc
title: Remove the commitment nonce from `CommitmentPayload`

doc:
  - audience: [Runtime Dev, Node Operator]
    description: |
      `CommitmentPayload` no longer carries a nonce field. Providers signing
      checkpoints must rebuild against the new payload layout; signatures
      produced by an older provider-node are rejected by the runtime.

crates:
  - name: pallet-storage-provider
    bump: major
  - name: storage-primitives
    bump: major

3. Audiences

Keep upstream's four audience IDs unchanged, so schema_user.json needs no edit. They map onto this system cleanly:

Audience ID	Who that is here
Runtime Dev	Building on pallet-storage-provider, pallet-drive-registry, pallet-s3-registry, or their precompiles
Runtime User	Submitting extrinsics, holding agreements, running challenges, reading state from a UI
Node Dev	Building against the provider node's HTTP API, or consuming storage-client / file-system-client / s3-client / @web3-storage/sdk
Node Operator	Running storage-provider-node, holding stake, exposed to slashing

Upstream's rule carries over verbatim and is the important one: anything that would result in an observable change to runtime behaviour must be marked Runtime User, and anything that modifies how the binary behaves must be marked Node Operator.

4. Auto-generation via the existing /cmd bot

The repository already runs polkadot-sdk's /cmd bot (.github/workflows/cmd.yml, cmd-run.yml), today exposing bench and fmt from scripts/cmd/cmd.py on the cmd-bot branch. This proposal adds upstream's prdoc subcommand to that same script:

/cmd prdoc --audience runtime_dev --bump patch

Upstream's .github/scripts/generate-prdoc.py fetches the PR patch from the GitHub API, seeds title from the PR title and the description from the PR body, and derives the crates: list by diffing the patch against the workspace. The author then edits the draft - upstream's docs are explicit that the generated file "will likely need to be edited to reflect the actual changes".

So the mechanical bookkeeping is automated; the audience and bump judgments are not, by design.

5. CI validation

Port upstream's .github/workflows/check-prdoc.yml as-is:

env:
  IMAGE: docker.io/paritytech/prdoc:v0.1.1
on:
  pull_request:
    types: [labeled, opened, synchronize, unlabeled]
  merge_group:

It runs prdoc check against the schema for format, then - unless the PR carries an R0 label - validates that prdoc/pr_<N>.prdoc exists via .github/scripts/check-prdoc.py.

Two upstream pieces are deliberately not ported:

• Backport PR-number extraction. Upstream parses Backport PR titles to find the original PR number. This repository has no stable release branches, so there is nothing to backport from.
• crates.io publishing integration. Upstream feeds crates: bump into parity-publish for ~500 published crates. Nothing here is published, so bump is recorded but consumes nothing downstream.

6. The R0 label

Adopt upstream's label and its narrow scope: R0-no-crate-publish-required, applied only to No-OP changes - a typo in a comment, CI-only churn. Upstream's guidance is "if unsure, ping the CODEOWNERS", and this repository already has a .github/CODEOWNERS to ping.

Dependabot PRs are the volume case here (#351, #350, #349 are recent examples) and would carry R0 via .github/dependabot.yml label config.

7. Release-time generation

Port upstream's scripts/release/build-changelogs.sh and its two tera templates. The pipeline:

prdoc load -d "prdoc/$VERSION" --json > data.json    # collect the release's files
# per audience: render only the doc entries tagged with that audience
tera -t templates/audience.md.tera  ... > relnote_<audience_id>.md
# plus a flat commit-style list of every entry
tera -t templates/changelog.md.tera ... > relnote_commits.md

audience.md.tera emits one section per audience, prefixed "ℹ️ These changes are relevant to: <description>", containing only the entries tagged for that audience. changelog.md.tera emits - #NNN: <title> (@author) for everything.

In release.yml, these sections are prepended to RELEASE_NOTES.md ahead of the existing "Add runtime info to changelog" step. The srtool digests and binary hashes stay exactly as they are, below the narrative.

Start by reading .github/workflows/cmd.yml, cmd-run.yml, and scripts/cmd/cmd.py to understand the existing /cmd bot, then review the proposed .prdoc.toml and upstream prdoc setup. Trace .github/workflows/check-prdoc.yml, .github/scripts/check-prdoc.py, scripts/release/build-changelogs.sh, and .github/workflows/release.yml. Done means PR documentation is validated, generated for releases, and included before the existing runtime details.