Sync annotated specs with upstream #41
Open
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.pythat 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
To bump specs to latest version, or bump the git submodule to the specific tag.
Run the sync script
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.