[go: up one dir, main page]

meta-issue: shift doc to new protocol

[replaces private meta-issue nomadic-labs/tezos#462]

This meta-issue lists the changes to be done to the documentation when a new protocol appears or disappears:

  • upon protocol activation (hence, the old protocol is dropped)
  • upon protocol snapshot (hence, the doc of the future proposal is added)

Protocol activation

The changes essentially concern switching the protocol documented as active (and the documented test networks) to the new protocol.

The needed changes are:

  • delete the directory containing the doc of the deactivated old protocol O
  • update docs/Makefile
    • search for mentions of protocol O, both by its name and by its number!
  • search for TODO tags on the current issue number in all files under docs/ and apply the instructions (add/remove TODO tags if needed)
  • remove files in docs/api/ concerning protocol O
  • link in the doc of the newly activated protocol N:
    • use scripts/add_labels_without_proto.py for adding un-versioned labels in pages for N (create a new directory N'; run the script on each file N/x.rst to produce N'/x.rst; control result by diff N N'; and then remove N and rename N' as N)
    • retarget symbolic link active to N instead of O
    • test the labels for all protocol doc versions using make -C docs xrefscheck and fix the errors if any
  • test the CI job test-doc-scripts, and update if needed (e.g. a version of Linux is no more supported or a new one gets supported)
    • test the job: either
      • make -C docs installcheck
      • watch the CI jobs tests:oc.install* in the MR you create
    • if the needed Tezos packages for the new protocol (including binaries such as the baker for protocol N) are not available, contact their providers (see https://tezos.gitlab.io/releases/releases.html, currently @diogo Castro)
    • update the test script test-doc-scripts.sh and its callees, if needed
    • update the CI job in .gitlab/ci/jobs/test/install_octez.yml if needed
  • update the active protocol name in other files outside docs/ if needed:
    • scripts/shellcheck_skips (if applicable)
    • (but don't update script-inputs/active_protocol_versions)
  • update the index.rst file
    • mind moving the page from protocol O from this main index to protocols/history.rst
  • update the _redirects.s3 file
  • update the .gitignore file (the one under docs/)
  • build the full doc, locally and in the CI, and fix any remaining errors

Examples:

Follow-ups:

  • Although not impacting the doc, mind removing dead code from frozen protocols (see !3537 (merged)).

Protocol snapshot

The changes essentially concern creating doc pages for the proposed protocol. This is done mostly automatically by scripts/snapshot_alpha.sh (called by snapshot_alpha_and_link.sh).

Additional manual changes (indicated by TODO tags pointing to this issue #2170):

  • patch docs/doc_gen/rpc_doc.ml and docs/doc_gen/dune (no more needed after merging !10307 (merged))
  • patch docs/Makefile
    • search for mentions of protocol N-1, both by its name and by its number!
  • generate the RPC reference for the new protocol N with make N/rpc.rst, then add this file to git
  • If N requires a new protocol environment, check that the doc has been updated according to meta-issue #4155 (grep for this issue number in all doc pages, and fix at least the pages for N; and ideally also the ones for Alpha)
  • follow-ups:
    • reset the Alpha changelog protocols/alpha.rst
    • add new test network in introduction/test_networks.rst and https://tezos.gitlab.io/user/multinetwork.html#built-in-networks ?
    • add a section in docs/api/openapi.rst and JSON files in docs/api/ concerning protocol N

Examples:

Edited by Nic Volanschi