ZAP: Zulip architecture proposal process #1
Conversation
Signed-off-by: Anders Kaseorg <[email protected]>
|
|
||
| The Zulip architecture proposal (ZAP) process gives the Zulip core team a | ||
| moderately more formal way to propose, collaborate on, and build consensus for | ||
| design proposals. |
There was a problem hiding this comment.
"engineering design" perhaps?
| GitHub pull requests for the implementation of individual Zulip features. We | ||
| expect that most smaller decisions will continue to be made in those ways, and | ||
| the ZAP process will be used in planning more substantial changes that will | ||
| benefit from it. |
There was a problem hiding this comment.
Maybe mention the "api design" stream process here as well?
| repository as the server code. However, the developer documentation is intended | ||
| to document Zulip as currently implemented; it has different maintenance and | ||
| lifecycle needs from proposals that may pertain to a future or past | ||
| implementation changes. |
There was a problem hiding this comment.
Maybe add a sentence of the form "Where appropriate, content can be copied from a ZAP into the developer documentation once the ZAP is implemented; but rarely will it make sense for a ZAP document to be copied in its entirely, since the audience and goals are different."
|
Should we link to this document in |
| Some categories of proposed changes to the Zulip architecture pose backwards | ||
| compatibility concerns if we get them wrong. |
There was a problem hiding this comment.
On first read, I was thinking that this paragraph covered the kinds of changes that this process was for, and the rest of the section was going to be further elaboration from there. To signpost the section's structure up front a bit more, perhaps something like this:
| Some categories of proposed changes to the Zulip architecture pose backwards | |
| compatibility concerns if we get them wrong. | |
| There are several reasons a given proposed change to the Zulip architecture | |
| can benefit from an explicit design proposal through the ZAP process. | |
| Some categories of proposed changes pose backwards | |
| compatibility concerns if we get them wrong. |
| The documents in `zulip-architecture` will be maintained to reflect the current | ||
| consensus of the project. (This maintenance may involve using issues and pull |
There was a problem hiding this comment.
This sounds a lot like it's saying that we'll maintain old accepted ZAPs to reflect the current design of the respective features.
I think that's not what you intend, because that was a major reason not to do this in the developer docs in the server/web repo.
What I imagine us doing is roughly:
- When we change our mind about something while an accepted ZAP is still in the process of being implemented, we'll typically edit the ZAP to reflect that.
- When the implementation is complete, we'll edit the metadata at the top of the ZAP to say so, and to link to the relevant subsystem doc and/or API docs.
- As we go on to tweak things thereafter, we generally won't try to update the ZAP to match. It remains a record of what we were thinking then; people finding the ZAP and interested in the up-to-date API are advised to follow the links to current docs.
- If we subsequently make a major overhaul — roughly, something that calls for a ZAP of its own — then we go back and add a link at the top of the older ZAP to point to the new one, a bit like the references at the top of old RFCs.
There was a problem hiding this comment.
I agree that ZAP should not be a living documentation but a document recording past consensus.
The proposed bullet points make sense to me. To implement this, we could use the concept of "status". A ZAP can be draft (when the initial PR is still open), accepted (when the initial PR is merged), or final (when the proposed change is implemented and documented).
Prior to the final phase, a ZAP can be modified, but major changes would require a new ZAP. A final ZAP should link to the relevant documentation in a Final References section. When the ZAP is superseded or overwritten, we link to the new ZAP in Final References.
| may choose to open a Zulip architecture proposal (ZAP). | ||
|
|
||
| A ZAP is a pull request in this `zulip-architecture` repository that adds a | ||
| Markdown document named like `text/0000-my-feature.md`. The numerical ID should |
Rendered