Skip to content

Conversation

@dapplion
Copy link
Member

@dapplion dapplion commented Nov 13, 2025

The annotated spec is an extremely valuable resource that has helped a large number of core devs to understand the spec. There's a lot of nuance and rationale not captured by the spec, which strives to remain minimal.

However, the annotated spec is a parallel document that goes out of sync with upstream specs. This PR adds a script scripts/sync.py that updates the annotated specs blocks to match the upstream specs. Annotated comments are kept marked by <!-- NOTES-BEGIN --> comments.

This PR already updates all existing annotated specs to the latest versions with great effort to keep all existing comments. Next I want to contribute annotated specs for Electra, Fulu and Glamsterdam. I also volunteer to keep updating the annotated specs as the upstream consensus specs mutate.

DX for initial note writer

Find a section you want to annotate, insert <!-- NOTES-BEGIN --> at the end of the section, and write any markdown you want expect headings: including new code blocks, pictures, etc.

DX for annotated spec mantainer

Run the script

./scripts/update_consensus_tag.sh

To bump specs to latest version, or bump the git submodule to the specific tag.

Run the sync script

./scripts/sync.py

It will produce a diff matching all sections to upstream and updating the content of the existing ones. If sections have been renamed, just move the notes around. If code has change, consider updating the notes content and rationale.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant