mirror of https://github.com/zcash/zips.git
Draft ZIP guide.
Signed-off-by: Daira Hopwood <daira@jacaranda.org>
This commit is contained in:
parent
d3bebc6c49
commit
caa5da0cc2
|
@ -0,0 +1,127 @@
|
|||
::
|
||||
|
||||
ZIP: Unassigned {numbers are assigned by ZIP editors}
|
||||
Title: {Something Short and To the Point}
|
||||
Owners: First Owner <email>
|
||||
...
|
||||
Credits: First Credited <optional email>
|
||||
...
|
||||
Status: Draft
|
||||
Category: {Consensus | Standards Track | Informational | Process}
|
||||
Created: yyyy-mm-dd
|
||||
License: {usually MIT}
|
||||
|
||||
|
||||
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 terms below are to be interpreted as follows:
|
||||
|
||||
{Term to be defined}
|
||||
{Definition.}
|
||||
{Another term}
|
||||
{Definition.}
|
||||
|
||||
|
||||
Abstract
|
||||
========
|
||||
|
||||
{Describe what this proposal does, typically in a few paragraphs.}
|
||||
|
||||
{Use links where applicable, e.g. [#protocol]_.}
|
||||
|
||||
|
||||
Motivation
|
||||
==========
|
||||
|
||||
{Why is this proposal needed?
|
||||
|
||||
This is one of the most important sections of the ZIP, and should be detailed
|
||||
and comprehensive. It shouldn't include any of the actual specification --
|
||||
don't put conformance requirements in this section.
|
||||
|
||||
Explain the status quo, why the status quo is in need of improvement,
|
||||
and if applicable, the history of how this area has changed. Then describe
|
||||
*at a high level* why this proposed solution addresses the perceived issues.
|
||||
It is ok if this is somewhat redundant with the abstract, but here you can
|
||||
go into a lot more detail.}
|
||||
|
||||
|
||||
Requirements
|
||||
============
|
||||
|
||||
{Describe design constraints on, or goals for the solution -- typically one
|
||||
paragraph for each constraint or goal. Again, don't actually specify anything
|
||||
here; this section is primarily for use as a consistency check that what is
|
||||
specified meets the requirements.}
|
||||
|
||||
|
||||
Non-requirements
|
||||
================
|
||||
|
||||
{This section is entirely optional. If it is present, it describes issues that
|
||||
the proposal is *not* attempting to address, that someone might otherwise think
|
||||
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.
|
||||
|
||||
Avoid overspecification! Also avoid underspecification. Specification is hard.
|
||||
Don't be afraid to ask for help.
|
||||
|
||||
Unless the specification is particularly simple, you will need to organise it under
|
||||
subheadings.}
|
||||
|
||||
Example subheading
|
||||
------------------
|
||||
|
||||
{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?
|
||||
|
||||
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.}
|
||||
|
||||
Valid reStructuredText
|
||||
----------------------
|
||||
|
||||
This is optional before publishing a PR, but to check whether a document is valid
|
||||
reStructuredText, first install rst2html5::
|
||||
|
||||
sudo apt-get install python-pip
|
||||
sudo pip install rst2html5
|
||||
|
||||
and then run::
|
||||
|
||||
rst2html5 -v zip-xxxx.rst >zip-xxxx.html
|
||||
|
||||
and view ``zip-xxxx.html`` in a web browser.
|
||||
|
||||
|
||||
Reference implementation
|
||||
========================
|
||||
|
||||
{This section is entirely optional; if present, it usually gives links to zcashd or
|
||||
zebrad PRs.}
|
||||
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
.. [#RFC2119] `Key words for use in RFCs to Indicate Requirement Levels <https://tools.ietf.org/html/rfc2119>`_
|
||||
.. [#protocol] `Zcash Protocol Specification, Version {...} or later [Overwinter+Sapling+Blossom] <https://github.com/zcash/zips/blob/master/protocol/protocol.pdf>`_
|
||||
.. [#zip-xxxx] `ZIP xxxx: Title <https://github.com/zcash/zips/blob/master/zip-xxxx.rst>`_
|
Loading…
Reference in New Issue