zec
/
zips
mirror of https://github.com/zcash/zips.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[zip-guide] Expand on conventions for Terminology, Specification, and References (#645) 

* [zip-guide] Expand on conventions for Terminology, Specification, and References.

Signed-off-by: Daira Hopwood <daira@jacaranda.org>

* Update zip-guide.rst

Signed-off-by: Daira Hopwood <daira@jacaranda.org>
Co-authored-by: Deirdre Connolly <durumcrustulum@gmail.com>
This commit is contained in:
Daira Hopwood 2022-11-09 21:08:50 +00:00 committed by GitHub
parent 0f33bb41a2
commit 9b2ae79baf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 136 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
zip-guide.html
View File

@ -3,6 +3,7 @@
<head>
<title>ZIP guide: {Something Short and To the Point}</title>
<meta charset="utf-8" />
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js?config=TeX-AMS-MML_HTMLorMML"></script>
<meta name="viewport" content="width=device-width, initial-scale=1"><link rel="stylesheet" href="css/style.css"></head>
<body>
<section>
@ -22,7 +23,10 @@ Pull-Request: &lt;<a href="https://github.com/zcash/zips/pull/253">https://githu
<p>{Delete this section.}</p>
</section>
<section id="terminology"><h2><span class="section-heading">Terminology</span><span class="section-anchor"> <a rel="bookmark" href="#terminology"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>{Edit this to reflect the key words that are actually used.} The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to be interpreted as described in RFC 2119. <a id="footnote-reference-1" class="footnote_reference" href="#rfc2119">1</a></p>
<p>{Edit this to reflect the key words that are actually used.} The key words "MUST", "REQUIRED", "MUST NOT", "SHOULD", and "MAY" in this document are to be interpreted as described in RFC 2119. <a id="footnote-reference-1" class="footnote_reference" href="#rfc2119">1</a></p>
<p>{Avoid duplicating definitions from other ZIPs. Instead use wording like this:}</p>
<p>The terms "Mainnet" and "Testnet" in this document are to be interpreted as defined in the Zcash protocol specification <a id="footnote-reference-2" class="footnote_reference" href="#protocol-networks">5</a>.</p>
<p>The term "full validator" in this document is to be interpreted as defined in the Zcash protocol specification <a id="footnote-reference-3" class="footnote_reference" href="#protocol-blockchain">4</a>.</p>
<p>The terms below are to be interpreted as follows:</p>
<dl>
<dt>{Term to be defined}</dt>
@ -34,7 +38,7 @@ Pull-Request: &lt;<a href="https://github.com/zcash/zips/pull/253">https://githu
<section id="abstract"><h2><span class="section-heading">Abstract</span><span class="section-anchor"> <a rel="bookmark" href="#abstract"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>{Describe what this proposal does, typically in a few paragraphs.</p>
<p>The Abstract should only provide a summary of the ZIP; the ZIP should remain complete without the Abstract.</p>
<p>Use links where applicable, e.g. <a id="footnote-reference-2" class="footnote_reference" href="#protocol">2</a> <a id="footnote-reference-3" class="footnote_reference" href="#protocol-introduction">3</a>.}</p>
<p>Use links where applicable, e.g. <a id="footnote-reference-4" class="footnote_reference" href="#protocol">2</a> <a id="footnote-reference-5" class="footnote_reference" href="#protocol-introduction">3</a>.}</p>
</section>
<section id="motivation"><h2><span class="section-heading">Motivation</span><span class="section-anchor"> <a rel="bookmark" href="#motivation"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>{Why is this proposal needed?</p>
@ -48,19 +52,38 @@ Pull-Request: &lt;<a href="https://github.com/zcash/zips/pull/253">https://githu
<p>{This section is entirely optional. If it is present, it describes issues that the proposal is <em>not</em> attempting to address, that someone might otherwise think it does or should.}</p>
</section>
<section id="specification"><h2><span class="section-heading">Specification</span><span class="section-anchor"> <a rel="bookmark" href="#specification"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>{This section describes what should change, using precise language and conformance key words. Anything that is <em>required in order to implement the ZIP</em> (or follow its process, in the case of a Process ZIP) should be in this section.</p>
<p>{Replace this entire section.}</p>
<p>The Specification section describes what should change, using precise language and conformance key words. Anything that is <em>required in order to implement the ZIP</em> (or follow its process, in the case of a Process ZIP) should be in this section.</p>
<p>Avoid overspecification! Also avoid underspecification. Specification is hard. Don't be afraid to ask for help.</p>
<p>Unless the specification is particularly simple, you will need to organise it under subheadings.}</p>
<p>Feel free to copy from other ZIPs doing similar things, e.g. defining RPC calls, consensus rules, etc.</p>
<p>ZIPs MUST take into account differences between the Zcash Mainnet and Testnet <a id="footnote-reference-6" class="footnote_reference" href="#protocol-networks">5</a> where applicable. A consensus ZIP MUST be able to be deployed on both Mainnet and Testnet.</p>
<p>Unless the specification is particularly simple, you will need to organise it under subheadings.</p>
<section id="example-subheading"><h3><span class="section-heading">Example subheading</span><span class="section-anchor"> <a rel="bookmark" href="#example-subheading"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>{At least while the ZIP is in Draft, we encourage writing open questions and TODOs.}</p>
<p>At least while the ZIP is in Draft, we encourage writing open questions and TODOs.</p>
<section id="open-questions"><h4><span class="section-heading">Open questions</span><span class="section-anchor"> <a rel="bookmark" href="#open-questions"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h4>
<ul>
<li>What happens if a full node can't parse the fandangle as a doohicky?</li>
<li>What happens if a full validator can't parse the fandangle as a doohicky?</li>
</ul>
<p>TODO: define byte encoding for the Jabberwock.</p>
<p>{Feel free to copy from other ZIPs doing similar things, e.g. defining RPC calls, consensus rules, etc.}</p>
</section>
</section>
<section id="comparison-of-zips-to-rfcs"><h3><span class="section-heading">Comparison of ZIPs to RFCs</span><span class="section-anchor"> <a rel="bookmark" href="#comparison-of-zips-to-rfcs"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Like RFCs, ZIPs are precise technical documents that SHOULD give enough implementation to implement part of a Zcash-related protocol or follow a Zcash-related process.</p>
<p>ZIPs are different from RFCs in the following ways:</p>
<ul>
<li>Many (but not all) ZIPs are "living documents"; they are updated in-place as the relevant areas of the protocol or process change. Unlike in the RFC process, making a change in an area described by a published ZIP does not <em>necessarily</em> require creating a new ZIP, although that is an option if the change is extensive enough to warrant it.</li>
<li>The expected structure of a ZIP is more constrained than an RFC. For example, the Specification section is REQUIRED, and all of the conformance requirements MUST go in that section. The ZIP editors will help you to ensure that things go in the right sections.</li>
<li>Security considerations SHOULD be spread throughout the text, in the places where they are most relevant.</li>
</ul>
</section>
<section id="using-mathematical-notation"><h3><span class="section-heading">Using mathematical notation</span><span class="section-anchor"> <a rel="bookmark" href="#using-mathematical-notation"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Embedded
<span class="math">\(\LaTeX\)</span>
is allowed and encouraged in ZIPs. The syntax for inline math is "<code>:math:`latex code`</code>" in reStructuredText or "<code>$latex code$</code>" in Markdown. The rendered HTML will use KaTeX <a id="footnote-reference-7" class="footnote_reference" href="#katex">6</a>, which only supports a subset of
<span class="math">\(\LaTeX\!\)</span>
, so you will need to double-check that the rendering is as intended.</p>
<p>In general the conventions in the Zcash protocol specification SHOULD be followed. If you find this difficult, don't worry too much about it in initial drafts; the ZIP editors will catch any inconsistencies in review.</p>
</section>
<section id="valid-restructuredtext"><h3><span class="section-heading">Valid reStructuredText</span><span class="section-anchor"> <a rel="bookmark" href="#valid-restructuredtext"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>This is optional before publishing a PR, but to check whether a document is valid reStructuredText, first install <code>rst2html5</code>. E.g. on Debian-based distros:</p>
<pre>sudo apt install python3-pip pandoc perl sed
@ -69,6 +92,10 @@ pip3 install docutils==0.19 rst2html5</pre>
<pre>make zip-xxxx.html</pre>
<p>(or just <code>make</code>) and view <code>zip-xxxx.html</code> in a web browser.</p>
</section>
<section id="conventions-for-references"><h3><span class="section-heading">Conventions for references</span><span class="section-anchor"> <a rel="bookmark" href="#conventions-for-references"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>For references to the Zcash protocol specification, prefer to link to a section anchor, and name the reference as <code>[#protocol-&lt;anchor&gt;]</code>. This makes it more likely that the link will remain valid if sections are renumbered or if content is moved. The anchors in the protocol specification can be displayed by clicking on a section heading in most PDF viewers. References to particular sections should be versioned, even though the link will point to the most recent stable version.</p>
<p>Do not include the "<code>https://zips.z.cash/</code>" part of URLs to ZIPs or the protocol spec.</p>
</section>
</section>
<section id="reference-implementation"><h2><span class="section-heading">Reference implementation</span><span class="section-anchor"> <a rel="bookmark" href="#reference-implementation"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>{This section is entirely optional; if present, it usually gives links to zcashd or zebrad PRs.}</p>
@ -86,7 +113,7 @@ pip3 install docutils==0.19 rst2html5</pre>
<tbody>
<tr>
<th>2</th>
<td><a href="protocol/protocol.pdf">Zcash Protocol Specification, Version 2020.1.24 or later</a></td>
<td><a href="protocol/protocol.pdf">Zcash Protocol Specification, Version 2022.3.8 or later</a></td>
</tr>
</tbody>
</table>
@ -94,14 +121,38 @@ pip3 install docutils==0.19 rst2html5</pre>
<tbody>
<tr>
<th>3</th>
<td><a href="protocol/protocol.pdf#introduction">Zcash Protocol Specification, Version 2020.1.24. Section 1: Introduction</a></td>
<td><a href="protocol/protocol.pdf#introduction">Zcash Protocol Specification, Version 2022.3.8. Section 1: Introduction</a></td>
</tr>
</tbody>
</table>
<table id="protocol-blockchain" class="footnote">
<tbody>
<tr>
<th>4</th>
<td><a href="protocol/protocol.pdf#blockchain">Zcash Protocol Specification, Version 2022.3.8. Section 3.3: The Block Chain</a></td>
</tr>
</tbody>
</table>
<table id="protocol-networks" class="footnote">
<tbody>
<tr>
<th>5</th>
<td><a href="protocol/protocol.pdf#networks">Zcash Protocol Specification, Version 2022.3.8. Section 3.12: Mainnet and Testnet</a></td>
</tr>
</tbody>
</table>
<table id="katex" class="footnote">
<tbody>
<tr>
<th>6</th>
<td><a href="https://katex.org/">KaTeX - The fastest math typesetting library for the web</a></td>
</tr>
</tbody>
</table>
<table id="zip-0000" class="footnote">
<tbody>
<tr>
<th>4</th>
<th>7</th>
<td><a href="zip-0000">ZIP 0: ZIP Process</a></td>
</tr>
</tbody>

87
zip-guide.rst
View File

@ -29,8 +29,16 @@ Terminology
===========
{Edit this to reflect the key words that are actually used.}
The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to
be interpreted as described in RFC 2119. [#RFC2119]_
The key words "MUST", "REQUIRED", "MUST NOT", "SHOULD", and "MAY" in this
document are to be interpreted as described in RFC 2119. [#RFC2119]_
{Avoid duplicating definitions from other ZIPs. Instead use wording like this:}
The terms "Mainnet" and "Testnet" in this document are to be interpreted as
defined in the Zcash protocol specification [#protocol-networks]_.
The term "full validator" in this document is to be interpreted as defined in
the Zcash protocol specification [#protocol-blockchain]_.
The terms below are to be interpreted as follows:
@ -87,30 +95,70 @@ it does or should.}
Specification
=============
{This section describes what should change, using precise language and conformance
key words. Anything that is *required in order to implement the ZIP* (or follow its
process, in the case of a Process ZIP) should be in this section.
{Replace this entire section.}
The Specification section describes what should change, using precise language and
conformance key words. Anything that is *required in order to implement the ZIP*
(or follow its process, in the case of a Process ZIP) should be in this section.
Avoid overspecification! Also avoid underspecification. Specification is hard.
Don't be afraid to ask for help.
Feel free to copy from other ZIPs doing similar things, e.g. defining RPC calls,
consensus rules, etc.
ZIPs MUST take into account differences between the Zcash Mainnet and Testnet
[#protocol-networks]_ where applicable. A consensus ZIP MUST be able to be deployed
on both Mainnet and Testnet.
Unless the specification is particularly simple, you will need to organise it under
subheadings.}
subheadings.
Example subheading
------------------
{At least while the ZIP is in Draft, we encourage writing open questions and TODOs.}
At least while the ZIP is in Draft, we encourage writing open questions and TODOs.
Open questions
''''''''''''''
* What happens if a full node can't parse the fandangle as a doohicky?
* What happens if a full validator can't parse the fandangle as a doohicky?
TODO: define byte encoding for the Jabberwock.
{Feel free to copy from other ZIPs doing similar things, e.g. defining RPC calls,
consensus rules, etc.}
Comparison of ZIPs to RFCs
--------------------------
Like RFCs, ZIPs are precise technical documents that SHOULD give enough
implementation information to implement part of a Zcash-related protocol or follow a
Zcash-related process.
ZIPs are different from RFCs in the following ways:
* Many (but not all) ZIPs are "living documents"; they are updated in-place as
the relevant areas of the protocol or process change. Unlike in the RFC process,
making a change in an area described by a published ZIP does not *necessarily*
require creating a new ZIP, although that is an option if the change is extensive
enough to warrant it.
* The expected structure of a ZIP is more constrained than an RFC. For example,
the Specification section is REQUIRED, and all of the conformance requirements
MUST go in that section. The ZIP editors will help you to ensure that things
go in the right sections.
* Security considerations SHOULD be spread throughout the text, in the places
where they are most relevant.
Using mathematical notation
---------------------------
Embedded :math:`\LaTeX` is allowed and encouraged in ZIPs. The syntax for inline
math is "``:math:`latex code```" in reStructuredText or "``$latex code$``" in
Markdown. The rendered HTML will use KaTeX [#katex]_, which only supports a subset
of :math:`\LaTeX\!`, so you will need to double-check that the rendering is as
intended.
In general the conventions in the Zcash protocol specification SHOULD be followed.
If you find this difficult, don't worry too much about it in initial drafts; the
ZIP editors will catch any inconsistencies in review.
Valid reStructuredText
----------------------
@ -127,6 +175,18 @@ Then, with ``zip-xxxx.rst`` in the root directory of a clone of this repo, run::
(or just ``make``) and view ``zip-xxxx.html`` in a web browser.
Conventions for references
--------------------------
For references to the Zcash protocol specification, prefer to link to a section
anchor, and name the reference as ``[#protocol-<anchor>]``. This makes it more likely
that the link will remain valid if sections are renumbered or if content is moved.
The anchors in the protocol specification can be displayed by clicking on a section
heading in most PDF viewers. References to particular sections should be versioned,
even though the link will point to the most recent stable version.
Do not include the "``https://zips.z.cash/``" part of URLs to ZIPs or the protocol spec.
Reference implementation
========================
@ -139,6 +199,9 @@ References
==========
.. [#RFC2119] `RFC 2119: Key words for use in RFCs to Indicate Requirement Levels <https://www.rfc-editor.org/rfc/rfc2119.html>`_
.. [#protocol] `Zcash Protocol Specification, Version 2020.1.24 or later <protocol/protocol.pdf>`_
.. [#protocol-introduction] `Zcash Protocol Specification, Version 2020.1.24. Section 1: Introduction <protocol/protocol.pdf#introduction>`_
.. [#protocol] `Zcash Protocol Specification, Version 2022.3.8 or later <protocol/protocol.pdf>`_
.. [#protocol-introduction] `Zcash Protocol Specification, Version 2022.3.8. Section 1: Introduction <protocol/protocol.pdf#introduction>`_
.. [#protocol-blockchain] `Zcash Protocol Specification, Version 2022.3.8. Section 3.3: The Block Chain <protocol/protocol.pdf#blockchain>`_
.. [#protocol-networks] `Zcash Protocol Specification, Version 2022.3.8. Section 3.12: Mainnet and Testnet <protocol/protocol.pdf#networks>`_
.. [#katex] `KaTeX - The fastest math typesetting library for the web <https://katex.org/>`_
.. [#zip-0000] `ZIP 0: ZIP Process <zip-0000.rst>`_