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
- use
- 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
- test the job: either
- 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
- mind moving the page from protocol O from this main index to
- update the
_redirects
file- hint:
ls *.rst | sed 's|^\(.*\).rst$|/O/\1.html /active/\1.html 301|'
- hint:
- update the
.gitignore
file (the one underdocs/
) - build the full doc, locally and in the CI, and fix any remaining errors
Examples:
- !11862 (merged) shift doc to Oxford2
- !9185 (merged) shift doc to Nairobi
- !8215 (merged) shift doc to Mumbai
- !7120 (merged) shift docs to lima
- !6379 (merged) shift docs to kathmandu
- !5750 (merged) shift to jakarta
- !4960 (merged) shift documentation to Ithaca
- !3450 (merged) shift documentation to Granada
- !2958 (merged) shift doc to 009
- !2639 (merged) shift to 008 doc
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(no more needed after merging !10307 (merged))docs/doc_gen/rpc_doc.ml
anddocs/doc_gen/dune
- 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
andhttps://tezos.gitlab.io/user/multinetwork.html#built-in-networks
? - add a section in
docs/api/openapi.rst
and JSON files indocs/api/
concerning protocol N
- reset the Alpha changelog
Examples:
- !5004 (merged) Jakarta
- !4226 (merged) Ithaca2
- !3522 (merged) Hangzhou
- !3016 (merged) Granada: Snapshot
- !2657 (merged) Snapshot Florence without baking accounts
Edited by Nic Volanschi