ZAP: Zulip architecture proposal process

[andersk]

Rendered

[PIG208]

Should we link to this document in README.md?

[gnprice]

Thanks for writing this up! A couple of small comments.

[gnprice]

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.

[PIG208]

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.

[timabbott]

I copied a version of this into the ZAP text but did not include draft/final terminology; that can be a future addition.

[gnprice]

Why "text"?

[PIG208]

Maybe zaps?

[timabbott]

We could also consider a draft/final directory split or something. I'm tempted to do nothing here until we have a clear reason to prefer a specific structure, so made no change related to this point.

[timabbott]

I resolved the above feedback as noted above (mostly just applying suggestions) and merged this. The document is probably not perfect, but it's also silly to actually be doing ZAPs based on this process with this still an open PR that we've not touched in so long.