Skip to content

Commit

Permalink
Merge pull request #935 from daira/zip-0-revising-zips
Browse files Browse the repository at this point in the history 
Suggested process for Update ZIPs
  • Loading branch information
@daira
daira authored Nov 5, 2024
2 parents d41fc33 + fddf80b commit 449804d
Show file tree
Hide file tree
Showing 2 changed files with 86 additions and 13 deletions.
37 changes: 28 additions & 9 deletions rendered/zip-0000.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,8 @@
<li>if it affects the consensus layer or the core protocol, assign a number in the range 200..299;</li>
<li>if it affects only higher layers but is needed for interoperability between node implementations or other parts of the ecosystem, assign a number in the range 300..399;</li>
<li>if it is specific to an implementation (e.g. zcashd or zebra), assign a number in the range 400..499;</li>
<li>if it concerns Consensus Process, assign a number in the range 0..9 or above 1000;</li>
<li>if it concerns Consensus Process, assign a number in the range 0..9 or 1000..1199;</li>
<li>if it only describes updates to existing ZIPs and/or the Zcash Protocol Specification (that will be a complete specification in themselves after deployment), assign a number in the range 2000..2999.</li>
<li>try to number ZIPs that should or will be deployed together consecutively (subject to the above conventions), and in a coherent reading order.</li>
</ul>
<p>These conventions are subject to change by consensus of the ZIP Editors.</p>
Expand Down Expand Up @@ -89,11 +90,22 @@
<p>For each new ZIP that comes in, the ZIP Editors SHOULD:</p>
<ul>
<li>Read the ZIP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don't seem likely to be accepted.</li>
<li>Check that the title accurately describes the content.</li>
<li>Ensure that the ZIP draft has been sent to the Zcash Community Forum and as a PR to the ZIPs git repository <a id="footnote-reference-7" class="footnote_reference" href="#zips-repo">9</a>.</li>
<li>Check that the Title, Category, and other metadata fields accurately describe the content.</li>
<li>Ensure that the ZIP draft has been submitted as a PR to the ZIPs git repository <a id="footnote-reference-7" class="footnote_reference" href="#zips-repo">9</a>. In some cases it may also be appropriate for it to be sent to the Zcash Community Forum.</li>
<li>Ensure that motivation and backward compatibility have been addressed, if applicable.</li>
<li>Check that the licensing terms are acceptable for ZIPs.</li>
</ul>
<p>For proposals to revise an existing ZIP, the ZIP Editors SHOULD:</p>
<ul>
<li>Read the proposed modification to check if it is ready: sound, complete, and non-disruptive to the ZIP's existing deployments if any.</li>
<li>If the proposed changes primarily affect already-deployed aspects of the Zcash consensus protocol, they SHOULD be specified in an "Update ZIP" describing the changes to be made, rather than directly as a pull request modifying the existing ZIP(s) or the Zcash Protocol Specification. At the discretion of the ZIP Editors, this might not be needed for compatible changes or clarifications.</li>
<li>If a change is to be made to an existing ZIP, check that the Title, Category, and other metadata fields still accurately describe the modified content.</li>
<li>Ensure that the update has been submitted as a PR to the ZIPs git repository <a id="footnote-reference-8" class="footnote_reference" href="#zips-repo">9</a>. In some cases it may also be appropriate for it to be sent to the Zcash Community Forum.</li>
<li>Ensure that motivation and backward compatibility have been addressed, if applicable.</li>
<li>Check that the licensing terms are still acceptable for ZIPs.</li>
</ul>
<p>If an Update ZIP is accepted, it is the responsibility of the ZIP Editors to apply the changes it describes to any existing specifications, but this MUST only be done once the Status of the Update ZIP has reached at least Proposed.</p>
<p>If a new Revision is added to a ZIP, then its original deployment is called Revision 0. In some cases the revisions of a ZIP may have differing deployment Status, which is expressed in the Status field as described in <a href="#zip-status-field">ZIP Status Field</a> below.</p>
</section>
<section id="reviewing-a-zip"><h3><span class="section-heading">Reviewing a ZIP</span><span class="section-anchor"> <a rel="bookmark" href="#reviewing-a-zip"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Any ZIP Editor can suggest changes to a ZIP. These suggestions are the opinion of the individual ZIP Editor. Any technical or process review that ZIP Editors perform is expected to be independent of their contractual or other relationships.</p>
Expand All @@ -115,7 +127,7 @@
<section id="rejecting-a-zip-or-update"><h3><span class="section-heading">Rejecting a ZIP or update</span><span class="section-anchor"> <a rel="bookmark" href="#rejecting-a-zip-or-update"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>The ZIP Editors MAY reject a new ZIP or an update to an existing ZIP, by consensus among the current Editors. Rejections can be based on any of the following reasons:</p>
<ul>
<li>it violates the Zcash Code of Conduct <a id="footnote-reference-8" class="footnote_reference" href="#conduct">4</a> ;</li>
<li>it violates the Zcash Code of Conduct <a id="footnote-reference-9" class="footnote_reference" href="#conduct">4</a> ;</li>
<li>it appears too unfocused or broad;</li>
<li>it duplicates effort in other ZIPs without sufficient technical justification (however, alternative proposals to address similar or overlapping problems are not excluded for this reason);</li>
<li>it has manifest security flaws (including being unrealistically dependent on user vigilance to avoid security weaknesses);</li>
Expand All @@ -132,7 +144,7 @@
<li>an update to an existing ZIP extends or changes its scope to an extent that would be better handled as a separate ZIP;</li>
<li>a new ZIP has a category that does not reflect its content, or an update would change a ZIP to an inappropriate category;</li>
<li>it violates any specific "MUST" or "MUST NOT" rule in this document;</li>
<li>the expressed political views of a Owner of the document are inimical to the Zcash Code of Conduct <a id="footnote-reference-9" class="footnote_reference" href="#conduct">4</a> (except in the case of an update removing that Owner);</li>
<li>the expressed political views of a Owner of the document are inimical to the Zcash Code of Conduct <a id="footnote-reference-10" class="footnote_reference" href="#conduct">4</a> (except in the case of an update removing that Owner);</li>
<li>it is not authorized by the stated ZIP Owners;</li>
<li>it removes an Owner without their consent (unless the reason for removal is directly related to a breach of the Code of Conduct by that Owner);</li>
<li>it violates a conformance requirement of any Active Process ZIP (including this ZIP).</li>
Expand All @@ -147,7 +159,7 @@
<li>by opening an issue on the <a href="https://github.com/zcash/zips/issues">ZIPs issue tracker</a>, or</li>
<li>by sending a message in the <a href="https://discord.com/channels/809218587167293450/809251050741170187">#zips channel on the Zcash R&amp;D Discord</a>.</li>
</ul>
<p><strong>All communications should abide by the Zcash Code of Conduct</strong> <a id="footnote-reference-10" class="footnote_reference" href="#conduct">4</a> <strong>and follow the GNU Kind Communication Guidelines</strong> <a id="footnote-reference-11" class="footnote_reference" href="#gnukind">5</a>.</p>
<p><strong>All communications should abide by the Zcash Code of Conduct</strong> <a id="footnote-reference-11" class="footnote_reference" href="#conduct">4</a> <strong>and follow the GNU Kind Communication Guidelines</strong> <a id="footnote-reference-12" class="footnote_reference" href="#gnukind">5</a>.</p>
</section>
<section id="zip-editor-meeting-practices"><h3><span class="section-heading">ZIP Editor Meeting Practices</span><span class="section-anchor"> <a rel="bookmark" href="#zip-editor-meeting-practices"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>The ZIP Editors SHOULD meet on a regular basis to review draft changes to ZIPs. Meeting times are agreed by consensus among the current ZIP Editors. A ZIP Editor meeting can be held even if some ZIP Editors are not available, but all Editors SHOULD be informed of significant decisions that are likely to be made at upcoming meetings.</p>
Expand All @@ -161,7 +173,7 @@
</section>
</section>
<section id="zip-format-and-structure"><h2><span class="section-heading">ZIP format and structure</span><span class="section-anchor"> <a rel="bookmark" href="#zip-format-and-structure"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>ZIPs SHOULD be written in reStructuredText <a id="footnote-reference-12" class="footnote_reference" href="#rst">6</a>, Markdown <a id="footnote-reference-13" class="footnote_reference" href="#markdown">7</a>, or LaTeX <a id="footnote-reference-14" class="footnote_reference" href="#latex">8</a>. For ZIPs written in LaTeX, a <code>Makefile</code> MUST be provided to build (at least) a PDF version of the document.</p>
<p>ZIPs SHOULD be written in reStructuredText <a id="footnote-reference-13" class="footnote_reference" href="#rst">6</a>, Markdown <a id="footnote-reference-14" class="footnote_reference" href="#markdown">7</a>, or LaTeX <a id="footnote-reference-15" class="footnote_reference" href="#latex">8</a>. For ZIPs written in LaTeX, a <code>Makefile</code> MUST be provided to build (at least) a PDF version of the document.</p>
<p>Each ZIP SHOULD have the following parts:</p>
<ul>
<li>Preamble — Headers containing metadata about the ZIP (<a href="#zip-header-preamble">see below</a>). The License field of the preamble indicates the licensing terms, which MUST be acceptable according to <a href="#zip-licensing">the ZIP licensing requirements</a>.</li>
Expand Down Expand Up @@ -208,11 +220,11 @@

&lt;/details&gt;</pre>
</li>
<li>Security and privacy considerations — If applicable, security and privacy considerations should be explicitly described, particularly if the ZIP makes explicit trade-offs or assumptions. For guidance on this section consider RFC 3552 <a id="footnote-reference-15" class="footnote_reference" href="#rfc3552">2</a> as a starting point.</li>
<li>Security and privacy considerations — If applicable, security and privacy considerations should be explicitly described, particularly if the ZIP makes explicit trade-offs or assumptions. For guidance on this section consider RFC 3552 <a id="footnote-reference-16" class="footnote_reference" href="#rfc3552">2</a> as a starting point.</li>
<li>Reference implementation — Literal code implementing the ZIP's specification, and/or a link to the reference implementation of the ZIP's specification. The reference implementation MUST be completed before any ZIP is given status “Implemented” or “Final”, but it generally need not be completed before the ZIP is accepted into “Proposed”.</li>
</ul>
<section id="zip-stubs"><h3><span class="section-heading">ZIP stubs</span><span class="section-anchor"> <a rel="bookmark" href="#zip-stubs"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>A ZIP stub records that the ZIP Editors have reserved a number for a ZIP that is under development. It is not a ZIP, but exists in the ZIPs git repository <a id="footnote-reference-16" class="footnote_reference" href="#zips-repo">9</a> at the same path that will be used for the corresponding ZIP if and when it is published. It consists only of a preamble, which MUST use Reserved as the value of the Status field.</p>
<p>A ZIP stub records that the ZIP Editors have reserved a number for a ZIP that is under development. It is not a ZIP, but exists in the ZIPs git repository <a id="footnote-reference-17" class="footnote_reference" href="#zips-repo">9</a> at the same path that will be used for the corresponding ZIP if and when it is published. It consists only of a preamble, which MUST use Reserved as the value of the Status field.</p>
<p>ZIP stubs can be added and removed, or replaced by the corresponding ZIP, at the discretion of the ZIP Editors. If a ZIP stub is removed then its number MAY be reused, possibly for an entirely different ZIP.</p>
</section>
<section id="zip-header-preamble"><h3><span class="section-heading">ZIP header preamble</span><span class="section-anchor"> <a rel="bookmark" href="#zip-header-preamble"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
Expand Down Expand Up @@ -288,6 +300,12 @@
<li>Final: When a Consensus or Standards ZIP is both implemented and activated on the Zcash network.</li>
<li>Obsolete: The status when a ZIP is no longer relevant (typically when superseded by another ZIP).</li>
</ul>
<p>If a ZIP has multiple Revisions, they may have differing deployment status. In that case the status of every Revision SHOULD be specified, using the format "[Revision 0] &lt;Status-0&gt;, [Revision 1] &lt;Status-1&gt;, ..." where "&lt;Status-n&gt;" is one of the alternatives above.</p>
<p>Once any Revision has been Released (as defined in the next section), all subsequent Revisions MUST also be at least Proposed (that is, they MUST NOT be Reserved or Draft). For example, a status such as:</p>
<blockquote>
<p>[Revision 0] Final, [Revision 1] Draft</p>
</blockquote>
<p>is not valid, because changes that are in Draft should not have been applied yet.</p>
<section id="specification-of-status-workflow"><h3><span class="section-heading">Specification of Status Workflow</span><span class="section-anchor"> <a rel="bookmark" href="#specification-of-status-workflow"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Owners of a ZIP MAY decide on their own to change the status between Draft or Withdrawn. All other changes in status MUST be approved by consensus among the current ZIP Editors.</p>
<p>A ZIP SHOULD only change status from Draft (or Rejected) to Proposed, when the Owner deems it is complete and there is rough consensus on the forums, validated by consensus among the current ZIP Editors. If it's a Consensus ZIP, a Deployment section MUST be present in order for the ZIP to change status to Proposed. Typically, although not necessarily, this will specify a network upgrade in which the consensus change is to activate.</p>
Expand All @@ -298,6 +316,7 @@
<p>A Process or Informational ZIP SHOULD change status from Proposed to Active when it achieves rough consensus on the forum or PR. Such a proposal is said to have rough consensus if it has been substantially complete and open to discussion on the forum or GitHub PR for at least one month, has been in Proposed status for at least one week, and no person maintains any unaddressed substantiated objections to it. Addressed or obstructive objections can be ignored/overruled by general agreement that they have been sufficiently addressed, but clear reasoning MUST be given in such circumstances.</p>
<p>When an Active, Implemented, or Final ZIP is no longer relevant –for example because its implementation has fallen out of use or its process is no longer followed– its status SHOULD be changed to Obsolete. This change MUST also be objectively verifiable and/or discussed. Final ZIPs MAY be updated; the specification is still in force but modified by another specified ZIP or ZIPs (check the optional Updated-By header).</p>
<p>If a non-editorial update is made to an Obsolete, Withdrawn, or Rejected ZIP, its status MUST be changed appropriately.</p>
<p>The above process also applies to any subsequent Revisions of a ZIP.</p>
</section>
</section>
<section id="zip-comments"><h2><span class="section-heading">ZIP Comments</span><span class="section-anchor"> <a rel="bookmark" href="#zip-comments"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
Expand Down
Loading

0 comments on commit 449804d

Please sign in to comment.