This is a document Sonya and I worked on a while back, and it sort of got a bit lost between the noise in out messages. I submitted a pull request, which was superseded by a google doc, and I think it is still not fully up to date.
Edit: I completely forgot to thank @mlphresearch for their feedback on this ages ago.
Edit: added Daira’s comments, to clarify the role of a zip editor. They are helpers not deciders.
I will make modifications as needed. This was not run past @daira or @gtank to the best of my knowledge. So any information or criticism they have I will adjust this to fit that.
Any comments by Daira, Gtank or Str4d on your zip is more important than this template.
It does look a bit confusing, but it is more or less the same as every protocol based zip is now. I have favoured bullet-points over paragraphs because the are easier for people who use English as a second language. Hence sometimes you will see contradictory statements in suggestions like “things SHOULD NOT be bullet pointed but MAY be.”
That said. Enjoy! I hope this helps. Please post questions, etc. below. I will be using this format for my proposals that I write for others. On with the show!
Welcome!
You’re reading an introduction to Zcash Improvement Proposals, and a step-by-step explanation of how to write your first ZIP draft
You are also encouraged to consult the ZIP guide. ZIP 0 documents the whole process in detail.
If this is your first time writing a ZIP, the structure and format may look intimidating. But really, it’s just meant to reflect common-sense practice and some technical conventions. Feel free to start with a simple initial draft that gets ideas across, even if it doesn’t quite follow this format. The community and ZIP editors will help you figure things out and get it into shape later.
What are ZIPs?
Submitting a Zcash Improvement Proposal is how you formally suggest changes to the Zcash protocol. You are also welcome to write a ZIP that asks for a decision about Zcash’s future to be recognized and recorded, even if it won’t impact the code.
ZIPs are debated extensively by the community, and carefully considered by representatives of the Zcash Foundation and the Electric Coin Company.
Decisions about whether proposed changes get into the Zcash protocol are made by ECC and the Zcash Foundation.
There are two ZIP editors, one ZIP editor represents ZF (currently George Tankersley) and one represents ECC (currently Daira Hopwood).
It is important to note that ZIP Editors do not have the authority or power to decide what becomes part of Zcash. They are editors, that is, their role is to ensure that ZIPs are editorially suitable as descriptions of proposed protocol or process changes.
That does involve some degree of technical assessment, but the role as ZIP Editors is mainly to make sure that the process is followed.
Before you start writing…
First, find out what the Zcash community thinks! Feedback and suggestions will help you create a thorough, high-quality ZIP. People may even be interested in helping you.
Explain what you think should happen, how it should work, and why you think it’s important. Often, some commenters will disagree with you — it’s important to hear them out and understand their objections, even if you don’t end up changing your mind.
Here are the best places to discuss ZIP ideas:
- The Zcash Community Forum, in the protocol section of the Community Collaborations category.
- The #zcash channel of the Zcash Community Chat.
You will have to create accounts for the forum and the chat, if you haven’t already signed up.
Vetting an idea publicly before going as far as writing a ZIP is meant to save both the potential Owner and the wider community time. Asking the Zcash community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the Owner. Just because an idea sounds good to the Owner does not mean it will work for most people in most areas where Zcash is used.
What goes into a ZIP/Pre-ZIP?
Some of these sections differ slightly in requirements from that of the ZIP template. This is to help the community help you.
If you have confusion the zip template is the cannancoical version.
The ZIP process is the required ECC process. the Pre-ZIP process is a community and foundation driven process to make ZIPS more accessible.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
Have special meaning and people should familiarise themselves with it. - RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
So The header is pretty much ZIP0 with a bit extra.
Pre-ZIP Header and description of fields
ZIP: unassigned
Title: My Community ZIP
Owner: mistfpga (zcash forums)
ZIP Status: Draft
Community Status: Request for comments : @ LINK TO DISCUSSION THREAD
Category: Process
Created: 2019-07-17
License: CC BY-SA 4.0 (Creative Commons Attribution-ShareAlike 4.0) [3]
- Owner has to either be a github account, email address or forum account where the person can be contacted about their proposal. It shouldn’t require personally identifiable information
- Status is always Draft until it is accepted
- Community Status, what part of the process is this zip at.
- Request for comments
- Request for proposal
- Request for technical review
- Final
- Discussion: Needs to include a link to the forum thread for discussion.
- Category: As defined by ZIP0
- Created: date of creation
- License: This has to be one of the licences outlined in ZIP0 if in doubt, “CC BY-SA 4.0 (Creative Commons Attribution-ShareAlike 4.0”
The changes are :
- Adds extra fields Community Status and Discussion
- Redefines owner
- Redefines ZIP to be Pre-ZIP - This is to indicate that it is community driven and may need extra help.
The Community Status is to let the community know what stage the proposer is at with the proposal. Whilst being in any stage, all comments are welcome, but it would probably serve the ECC, foundation and communities time a little better if they know what is expected of them in a reply.
The overall format for the Pre-ZIP should be something like:
- Header +
- Terminology +
- Out of Scope +
- Abstract/Spirit *
- Motivation *
- Requirements *&
- Specification *&
- Further discussion needed on *&
- Further discussion +
- Raised objections and issues. &
- Implications to other users. &
- Any process concerns or areas you would like help *
- Technical/Code implementation/implication &
- Technical/Code implementation/implication
stuff marked with * really need to be in the OP as a starting point for a Pre-ZIP
stuff marked with + is a nice to have, but this will change over the course of the Pre-ZIP.
stuff marked with & is either stuff based off community feedback so not realistic to expect in the OP but is needed for the Final.
Dont worry about the mandatory fields, just put in what you can, the community/foundation will help you with the rest, even the mandatory stuff.
Section 9 is probably out of scope for most Pre-ZIPs and better handled by the zip process. Maybe use this space for usecases or to show what bits of your suggestion are already implemented either on other projects or zcash.
2 Terminology
- RFC 2119 language MUST be used when expressing the requirements, capital letters MUST be used for the key word. They MAY be used in other parts of the proposal, if so it MUST to be indicated with capital letters.
- Any extra information that might need clarification. This will probably keep getting updated as people give feedback.
3 Out of Scope SHOULD use 2119 Language
- Anything that is explicitly not covered by the proposal.
- Should get updated with feedback from the community.
4 Abstract/Spirit: SHOULD NOT be bullet pointed, but MAY be bullet pointed.
- A short statement of what the zip is about.
- A short statement that emphasises what the proposer is trying to achieve with the zip.
5 Motivation: SHOULD NOT be bullet pointed, but MAY be bullet pointed.
A few short statements explaining your motivation for creating the zip. This may overlap with Spirit but it is not the same thing.
6 Requirements: (SHOULD be paragraphs but MAY be bullet pointed it MAY use 2119 language. MAY be paragraphs)
- This is one of the most important sections for the ECC
- Try to make this as detailed as possible.
- Do not include things that should be part of the specification.
- Try to explain what the situation is now and why your zip is needed.
- This section can be hard, but is very important. Don’t worry about getting it right first time. the community is here to help you with this.
- If you use paragraphs please remember that things do get lost in translation, you might end up bullet pointing you paragraphs. then turning them back to paragraphs for the zip process.
7 Specification: MUST be bullet pointed MUST use 2119 language
- Detailed list of what the change MUST/MUST not do. using 2119 language
- Keep to 1 point per line only. This is to make it easier for translation
- You can mix 2119 language in the same bullet point, but grammar might become an issue. try to keep it simple
- If in doubt use one line for the MUST and another for the SHOULD or MAY
- Again this can be tricky. It is better to be vague or say you don’t know and ask for community help.
8 Issues & Further Discussion
- Further discussion needed on :
- no guidelines on this section.
- it is freeform.
- Use it to ask questions of your own Pre-ZIP
- Use it to solicit specific requests for comments on certain issues
- Use it to highlight areas you are unsure of.
- bullet points and paragraphs are cool.
- Raised objections and issues:
- This will be an evolving part of the document and so it might be better suited to paragraphs or bullet points.
- Objections should be bullet pointed wherever possible and addressed if possible.
- Implications to other users. MAY use 2119 language
- This will be an evolving part of the document and so it might be better suited to paragraphs or bullet points. This will need regular updates and engagement from the proposer/advocate.
- Is for any concerns or areas you would like help
- This again is free form. Please use this space to request for help for things you do not understand, would like someone else to do really anything related to the process of making the zip rather than the contents of the zip (that is section 7a)
9 Technical/Code implementation/implication
This is very hard for the non zcash specialist programmer to know. The best I think we can do in this regard is maybe use this section for usecases and usescases that address objections in section 8.
