\[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: - !20536 shift doc to Tallinn - !11862 shift doc to Oxford2 - !9185 shift doc to Nairobi - !8215 shift doc to Mumbai - !7120 shift docs to lima - !6379 shift docs to kathmandu - !5750 shift to jakarta - !4960 shift documentation to Ithaca - !3450 shift documentation to Granada - !2958 shift doc to 009 - !2639 shift to 008 doc Follow-ups: - Although not impacting the doc, mind removing dead code from frozen protocols (see tezos/tezos!3537). # 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 tezos/tezos#2170): * ~~patch `docs/doc_gen/rpc_doc.ml` and `docs/doc_gen/dune`~~ (no more needed after merging !10307) * 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: - tezos/tezos!5004 Jakarta - tezos/tezos!4226 Ithaca2 - tezos/tezos!3522 Hangzhou - tezos/tezos!3016 Granada: Snapshot - ​​​​​​​ tezos/tezos!2657 Snapshot Florence without baking accounts