Revise ZEP0 #59
Revise ZEP0 #59
Conversation
active/ZEP0000.md
Outdated
| functionality, data types and features to accommodate emerging and essential | ||
| use cases. | ||
|
|
||
| - **Lean ZEP** |
There was a problem hiding this comment.
Can you provide an example for a Lean ZEP? Where would adding a codec fall?
There was a problem hiding this comment.
I agree with this comment. In particular, how will an author choose between an Extension ZEP and an Lean ZEP?
There was a problem hiding this comment.
Please see #59 (comment).
active/ZEP0000.md
Outdated
|
|
||
| The PR should contain the narrative document explaining the need, importance, | ||
| and use case for the change of the ZEP and should be submitted in the | ||
| zarr-specs repository with the name `zep-<n>: <title>.rst` under |
There was a problem hiding this comment.
Are there any fans of RST here?
There was a problem hiding this comment.
I would love to move to markdown.
|
|
||
| In unusual cases, the [Zarr Steering Council] may be asked to decide whether a | ||
| controversial ZEP is `Accepted`. | ||
| 1. **Stakeholder Engagement**: |
There was a problem hiding this comment.
A reader might ask: Who are the stakeholders and how do I contact them?
There was a problem hiding this comment.
Mostly the ZIC and ZSC but also the broader community.
The author is supposed to use the submitted PR to spread the word to everyone, but we also have Google groups set up for notification purposes.
There was a problem hiding this comment.
👍 to defining stakeholders clearly.
There was a problem hiding this comment.
Thanks for doing this Sanket! I think the introduction of the "lean ZEP" is a major improvement in process. Having all the changes and discussion in a single-threaded PR will make it much easier to discuss and review ZEPs.
I see no reason to limit the lean ZEP process to only minor changes. If anything, the more significant the proposal, the more important it is to be able to review and discuss clearly. I predict that, if we adopt this, nearly all future ZEPs will be declared as "lean ZEPs" mostly because it is easier for everyone involved. Who will be the arbiter of whether a ZEP is minor enough to qualify for a Lean ZEP? What will happen if someone submits a Lean ZEP which some people feel is scoped too large? Who will enforce turning it into a regular (old-style) ZEP?
So I would like the see the "lean ZEP" process simply become the process for all ZEPs, rather than the more complicated multiple PR / multiple repo process. I won't insist on that if there are others who think maintaining the original process is important. However, I'm curious who that is. Please 👍 this comment if you are in favor of simply making the "lean ZEP" process the default for all ZEPs. Or 👎 this comment if you would like to keep the multiple repo / multiple PR process for some ZEPs.
active/ZEP0000.md
Outdated
| functionality, data types and features to accommodate emerging and essential | ||
| use cases. | ||
|
|
||
| - **Lean ZEP** |
There was a problem hiding this comment.
I agree with this comment. In particular, how will an author choose between an Extension ZEP and an Lean ZEP?
active/ZEP0000.md
Outdated
|
|
||
| The PR should contain the narrative document explaining the need, importance, | ||
| and use case for the change of the ZEP and should be submitted in the | ||
| zarr-specs repository with the name `zep-<n>: <title>.rst` under |
There was a problem hiding this comment.
I would love to move to markdown.
active/ZEP0000.md
Outdated
| The PR should contain the specific changes to the Zarr specification without | ||
| requiring a separate narrative document. As Lean ZEPs involve minor and | ||
| non-controversial changes, a narrative document and the use of the template and | ||
| instructions file are not necessary. |
There was a problem hiding this comment.
This sounds like a great way to do ZEPs. Everything in one place! 🎉
|
I agree with @rabernat. Lean ZEPs sound great! My learning from the last ZEPs was that we need to engage the stakeholders earlier in the process and not only when presenting them with a final vote. Having the feedback earlier increases buy-in and reduces the number of post-vote changes. I don't think the solution to that problem is more phases and more votes in the process. On the contrary, I think we need to make the conversation easier to follow and actively reach out to ZIC and ZSC. That is why the Lean ZEP approach is appealing. It simplifies the process/paperwork and streamlines the conversation. I still think we need a mechanism of forcing a vote, though. Consensus seems ill-defined in a distributed, volunteer-driven community. |
In the spirit of copying PRs, I would advocate for keeping linear ZEP numbering. The ZEP process is its own artifact that gets created and modified through ZEPs. ZEP 0 introduced the process. This proposed modification should become its own ZEP. The wish for ZEP versioning almost seems like an artifact of a too complex ZEP process. If it were as easy to make and approve ZEPs like a PR, we could just introduce changes like the sharding "index_location" in a new ZEP. |
|
Regarding versioning, as I see it, a "ZEP" would just be the additional process taken for reviewing a non-editorial/non-trivial spec change (i.e. PR). Therefore, there would be no reason to version a "ZEP" except perhaps in its draft state, where you could potentially identify versions by git commit hashes, because once it is accepted it is merged into the spec and any further revisions would be done as a separate PR. In fact I would propose that the ZEP number be assigned based on the PR number. For example, let's say we add a "pack_bits" codec in PR 1234, that initially only supports "bool" data type. Then someone in PR 1255 adds support for a "uint4" data type and modifies the description of the "pack_bits" codec to also support "uint4". When we document what features are supported by each implementation, if not already explicit we could at this point update the descriptions to indicate that certain implementations support pack_bits with bool only while others support both bool and uint4. It might be useful to define as part of the spec a precise way to indicate support for various features. For example we could say that support for a given data type can be indicated by the "codecs/pack_bits/<data_type>" feature identifier. I'm not sure how important it is to specify these feature flags precisely, though. |
|
I think it is important to separate support for a feature of the Zarr specification in an implemention from the ZEP that introduced the feature.
I think an implementation needs to be able to decide during metadata parsing whether it can correctly understand a Zarr array/group. If it encounters unknown attributes, values or identifiers that would already indicate a lack of support. Basically, that means that new changes can only be additive (e.g. new attributes on existing codecs, new values for attributes, new codecs). |
To be clear, I was imagining that these feature identifiers would be solely for documentation purposes, similar to caniuse.com, not that they would appear in the metadata anywhere. |
|
Thanks all for the feedback so far. Here are my responses:
@rabernat: The changes which are minor and non-controversial would fall under the Lean ZEP category, e.g. zarr-developers/zarr-specs#256 or adding a new data type. The ZEP, which proposes a significant change to the specification and requires a reference implementation of the sort, should not be submitted under Lean ZEP, e.g. major specification version update (V3 → V4), extensions like sharding, variable chunking, etc. Categorising all ZEPs under Lean might lead to less involved participation in an important proposal from everyone involved. The reading and implementation phases ensure that the stakeholders are given enough time to read and work on implementing the proposal before it is finalised. I've outlined various issues we've encountered here: #55 (comment). I've also proposed removing the option for multiple repo/PR processes so that everything would take place in the zarr-specs repository.
@normanrz: Why do you think a multi-phase approach would not help have more engaged participation from the stakeholders? |
Adding data types or codecs can be controversial, too. I don't think it is possible to know a priori. That is why a community discussion is needed for every ZEP. PRs are a great tool for that.
Shouldn't all ZEPs come with a reference implementation or at least a proof-of-concept?
Everybody in the Zarr community is volunteering and very busy. Multi-phase processes require a lot of effort to understand and to follow. I might be wrong but I think that more complex processes can be intimidating and annoying both on the side of the ZEP authors, who need to chase the feedback/votes, and on the side of the community members, who are frequently pressured to issue feedback/votes. |
|
Resurrecting this PR after having discussions and feedback from various community and ZEP meetings. I have extended the scope of Lean ZEPs to add breaking changes if there is unanimous approval from participating stakeholders. This change is specifically targeted to include zarr-developers/zarr-specs#292 and other similar changes in the future. @normanrz, here are my responses to your last comment —
It can be. That's why it's recommended and preferred that an issue in the zarr-specs repo be created to have a community discussion before working on the actual PR for a ZEP; see here - 3rd para.
ZEPs which add new functionality by changing or extending the existing specification should be accompanied by an implementation/POC.
I understand that the phased approach requires involved participation from the active maintainers and implementors. I've outlined issues we've faced with the existing version of the ZEP process at #55 (comment) during ZEP1. We need a mechanism to avoid repeating those issues. I think the phased approach is one solution that could help us. If you have suggestions, let's discuss them. I'm all ears. :) Also, having all the discussions and comments in a single PR for the entirety of a ZEP proposal would be convenient for the author to facilitate feedback and votes from everyone involved. |
active/ZEP0000.md
Outdated
| The SPEC ZEP (abbreviation of Specification ZEP) for now introduces changes in | ||
| the core specification of Zarr. The changes related to core specification follow a | ||
| Specification ZEPs deal with the changes related to [Zarr Specifications]. The | ||
| SPEC ZEP (abbreviation of Specification ZEP) introduces changes to the |
There was a problem hiding this comment.
Unless "SPEC" is an acronym, it should not be all caps.
active/ZEP0000.md
Outdated
| strict and thorough review process and should be adopted by everyone in the | ||
| Zarr community. | ||
| Zarr community. Specification ZEPs are of two types. They are: | ||
|
|
||
| - **Core protocol ZEP** |
There was a problem hiding this comment.
what is the difference between a specification zep and a core protocol zep?
There was a problem hiding this comment.
ok I see, a core protocol zep is a subtype of a specification zep. What does the word "protocol" mean here? Are we just using that word to avoid re-using the word "specification"?
There was a problem hiding this comment.
The 'protocol' terminology was coined when we first introduced the idea of the ZEP process back in 2022.
Are we just using that word to avoid re-using the word "specification"?
I'm not sure about that. IIRC, the term 'protocol' was used heavily during V3 development in early 2019. I have no strong opinions about 'Protocol'.
There was a problem hiding this comment.
:+1 to eliminating Protocol and sticking with Specification.
|
Thanks for addressing some of our feedback and revising the ZEP. I think the lean ZEPs help to move the process in the right direction. However, a main problem we are currently facing is lack of (timely) responses from the council members. Without solving that problem, I don't think we will see significant improvements to the process. So, I think it is important to also move zarr-developers/governance#44 forward. |
|
It seems like a "lean ZEP" as defined in this PR is a spec change that gets approved without a formal ZEP process, and so I would argue that a "lean ZEP" is is not a ZEP, or at least it communicates very little to categorize such changes as ZEPs. Instead of requiring that every spec change fall into some ZEP category, It would be simpler to reserve the concept of "ZEP" for formal proposals that do observe a ZEP process. Instead of defining a "lean ZEP", this document can simply state that not all spec changes happen via ZEPs -- some spec changes, like typo fixes, or even semantically significant changes, can be proposed, discussed, and accepted via github PRs provided there is an exceptional level of consensus, bypassing the ZEP process completely. @normanrz wrote:
I agree with this completely. We are not bottlenecked by the lack of new ZEP categories (although it's important to define those carefully). We are bottlenecked because there is not enough developer time going into the spec. |
Extrapolating on this a bit, let me introduce a new idea here. Rather than adding additional ZEP categories, we do away with all but core-protocol ZEPs, reserving these for major and/or breaking changes to the specification. All other changes (e.g. bug fixes, clarifications) and/or extensions to the specification can be done as pull requests directly to the spec repo and merged through a much simpler process (ideally managed entirely by the spec core team -- not the ZEP process). |
|
I think the primary additions I'd make to your comment, @jhamman, would be:
|
|
Thanks, everyone, for your feedback. I understand the importance of adding changes to the spec via GitHub PRs. I'm in favour, but I'd like to keep the Lean ZEPs category in the process, as it'll help us maintain a record of changes that have gone in the spec in a readable manner — the original idea I proposed in this PR to combine Let me know what you think. ^ The discussion at zarr-developers/governance#44 is important, and I like what Josh proposed in zarr-developers/governance#44 (comment). I'd like to propose merging this PR unless strong objections exist to this current version. Successive PRs can be added for more changes or to reflect the progress/conclusion from zarr-developers/governance#44. |
I think @jhamman's proposal to slim down the ZEP process counts for me as a strong objection. We should at least discuss that as a viable alternative to this PR. @MSanKeys963 if the main goal is to record all spec changes on the zeps web page, then this can be done without introducing a new ZEP category -- we could display ZEPs and PRs together on that site, with a clear indication of which is which. |
Co-authored-by: Davis Bennett <[email protected]>
|
As per our @jhamman's #59 (comment), and discussion in the last community and ZEP meeting (notes here) with @joshmoore and @d-v-b — I've removed Lean ZEPs category in 81b7ca2. Also, see: #59 (comment). We discussed that zarr-developers/governance#44, when finalised, would mention when the Zarr-Specs core devs think it's necessary to follow the ZEP0 process to change the specification. The definition of these changes is yet to be decided, but they're mostly going to revolve around major changes like incrementing the specification version, change that involves participation from multiple implementations, and similar things. All other changes to the specifications would be done simply via a GitHub PRs. These PRs would be approved and merged by the Zarr-Specs core devs team (when formed). I've added multiple comments in the markdown document like: Please review. Thanks! |
Co-authored-by: Josh Moore <[email protected]>
Co-authored-by: Josh Moore <[email protected]>
|
@rabernat, @jakirkham, @alimanfoo, @ryan-williams: are there any changes you would like to see here? |
There was a problem hiding this comment.
This is great progress. Nice work @MSanKeys963!
I am excited by the simplifications this will bring.
My main feedback
- Let's clarify whether Specification ZEPs generate a new spec major version
- Let's eliminate extension ZEPs entirely
Meta question: should this change be done via a ZEP? 🤣
active/ZEP0000.md
Outdated
| groups using Zarr and the general Zarr community. The general advice is that | ||
| everyone should be made aware of changes introduced by core ZEPs. Core protocol | ||
| ZEPs require community consensus, and developers or users are typically not | ||
| free to ignore them. |
There was a problem hiding this comment.
Given the fact that we have decided not to version the V3 spec (see zarr-developers/zarr-specs#277), it would be helpful to state explicitly whether any core protocol ZEP (i.e. "changes in the core specification of Zarr") will generate a new major version of the spec.
In my opinion, these should go together. Any change major enough to warrant a core protocol ZEP would also trigger a major version increment. The next core protocol ZEP will produce Zarr V4.
There was a problem hiding this comment.
Done. Added via 3ae1fc5.
There was a problem hiding this comment.
There are definitely ways of evolving the spec in a way that is backwards compatible and, therefore, wouldn't necessitate a major version bump. I wouldn't make this an automatic thing for Core ZEPs. In fact, I think we should be very careful with version bumps and try hard to avoid them.
active/ZEP0000.md
Outdated
| strict and thorough review process and should be adopted by everyone in the | ||
| Zarr community. | ||
| Zarr community. Specification ZEPs are of two types. They are: | ||
|
|
||
| - **Core protocol ZEP** |
There was a problem hiding this comment.
:+1 to eliminating Protocol and sticking with Specification.
|
|
||
| In unusual cases, the [Zarr Steering Council] may be asked to decide whether a | ||
| controversial ZEP is `Accepted`. | ||
| 1. **Stakeholder Engagement**: |
There was a problem hiding this comment.
👍 to defining stakeholders clearly.
Co-authored-by: Ryan Abernathey <[email protected]>
|
Thanks for your reviews, @joshmoore and @rabernat! As per your feedback, I've removed extension ZEPs entirely as we're working on defining a new way to add extensions — currently under discussion in zarr-developers/zarr-specs#312 (comment) and zarr-developers/zarr-specs#316. I've also removed the Also, every core ZEP (removed the term 'protocol') will lead to a major version increment of the Zarr specification.
@rabernat: Instead of a new ZEP, let's use this PR to add the changes so we can move ahead! ;) |
Hi all. 👋🏻
This PR was last updated on: 10/15/2024
I'm proposing changes to our ZEP process, i.e. ZEP0, based on the discussions at #44, #52 and #55. Here are the major changes I'm proposing through this PR:
Addition of new ZEP type under Specification ZEPs category → Protocol Extension ZEPs→ Removed in 3ae1fc5. Please check Revise ZEP0 #59 (comment).Adding a new ZEP category → Lean ZEPs→ Removed in 81b7ca2. Please check Revise ZEP0 #59 (comment).There is also a question regarding the versioning of the ZEP proposal, which are modified after acceptance, for example ZEP0. There's a suggestion of using semantic versioning by @LDeakin in #55 (comment), which is something we can discuss and adopt.
PS. If we adopt semantic versioning, this update would be ZEP0.1. :)
Many thanks to @joshmoore, @rabernat, @jbms and others for the initial discussions regarding the ZEP0 revision.
Also, I've been fiddling around to merge the zeps and zarr-specs repository and have come up with: https://docs-test-sanket.readthedocs.io/en/latest/. I'd appreciate any feedback or comments on the new webpage design.
Please let me know what you think of this proposal. Also, please send this to folks interested in this conversation.
Preview: https://zeps--59.org.readthedocs.build/en/59/active/ZEP0000.html
CC: @zarr-developers/implementation-council @zarr-developers/steering-council