Updating readme #26
Updating readme #26
Conversation
There was a problem hiding this comment.
Thanks! Sorry, I'm just catching up on this - I wasn't tagged in the discourse discussion for some reason. I think the delta agreed upon in that thread was:
-
everything on stan-dev is open to discussion from everyone, and
-
everyone is welcome to become a developer.
Some more specific comments in there as well. Thank you!
|
|
||
| We welcome proposals and discussion from everyone in the community. | ||
|
|
||
| Our process for accepting proposals takes inspiration from [IETF Internet-Drafts](https://www.ietf.org/standards/ids/). We want the process to be lightweight and result in accepting documents that have consensus from the community at the time of approval. |
There was a problem hiding this comment.
It seems suboptimal to edit history here - this process was inspired by the Rust process. Maybe rephrase give a little more background on which parts we liked from that process and which parts we want to emphasize that we're doing differently? I think Bob gave a good minimal diff in the discourse discussion.
There was a problem hiding this comment.
Thanks for the comment. The point isn't to edit history, but to describe what the current process is. We could just remove this if having a reference doesn't help.
There was a problem hiding this comment.
I'd rather reference rust here as well, imo we want a rust rfc lite
There was a problem hiding this comment.
Is that actually what we want? It seemed like on the thread it wasn’t what we were doing or attempting to do. Happy to have that language if that really reflects what we want. (I’m agnostic. I read the Rust RFC and it doesn’t sound like what we’re attempting to do. Even the goals of it. It really sounds more like the IETF Internet-Drafts.)
| Our process for accepting proposals takes inspiration from [IETF Internet-Drafts](https://www.ietf.org/standards/ids/). We want the process to be lightweight and result in accepting documents that have consensus from the community at the time of approval. | ||
|
|
||
|
|
||
| ## Submit a Design Document |
There was a problem hiding this comment.
I think I liked this section better after the context for what design review is and when it's necessary, because then folks have to read or skip (and thus become aware) of those sections on the way to the meat of the process. What are your thoughts on the ordering here?
Updating it to not be in list form seems reasonable.
There was a problem hiding this comment.
I moved it all the way to the top intentionally; something should be at the top describing the goals and how and when things get merged. Maybe what would help is to have a second section below that gets into more detail?
|
|
||
| Design documents rarely go through the process unchanged, especially as alternatives and drawbacks are identified. Proposals can go through edits for months as we discuss major changes to Stan. Everyone in the community is welcome to make comments (relevant to the proposal). | ||
|
|
||
| Proposals are accepted and merged into this repository when there is consensus from the community. In practice, this means giving enough time for members of the community to review/comment/request changes on the proposal. Proposals can be accepted if at least one other (non-author) Stan developer endorses the final draft of the design document and there are no denials. |
There was a problem hiding this comment.
Please nix the consensus part here as well - that was intentionally not in the original. I don't think there is a majority of developers who want to move in a direction where major decisions require consensus, and we shouldn't sneak it in here like this.
There was a problem hiding this comment.
This is actually one of the recurring points that came forward in this discussion: https://discourse.mc-stan.org/t/process-for-design-docs/14956
Specific examples from the thread:
- "I also see it as a good place to hash out ideas, get “consensus” on larger things that will affect anyone (for example: latest Stan CI PR)." -- @rok-cesnovar
- "The design-doc repo is to gather broader consensus… but we don’t have a rule saying “if accepted as design-doc, then it must go through”." -- @wds15
- "The concept is build around consensus, but to me it’s still a lot more than mere “brainstorm”." -- @wds15
- @riddell-stan provides alternatives: "I have two alternatives to the consensus rule:". (This was actually incorporated into this document. The first alternate is proposed in the next line: "In practice, this means giving enough time for members of the community to review/comment/request changes on the proposal. Proposals can be accepted if at least one other (non-author) Stan developer endorses the final draft of the design document and there are no denials.")
- "In my view accepted means anyone that cared enough on a topic to review/comment/request changes agrees with the change. " -- @rok-cesnovar
- "I also agree we need some kind of approval process. Right now, we’re just assuming we’ll keep discussing until we get a consensus." -- @bob-carpenter
If there is a way to describe what we want better, let's do that! I honestly think the discussion has stated that they're striving for consensus. To be clear, we're talking about consensus having the definition of "general agreement." It's also a mix of the voting rule of "general consent," but since PRs aren't votes and we don't have a list of members that vote, we never have a vote so this doesn't apply. I think "consensus" is the right term (taking it to mean "most people that care would agree"), but happy to have different wording.
There was a problem hiding this comment.
Just for clarity "majority" doesn't equal "consensus."
Majority requires > 50% of some group.
There's also a second definition of consensus that applies: "the judgment arrived at by most of those concerned." And that's really what we're after.
There was a problem hiding this comment.
I think the last sentence in the document I proposed is incorrectly worded:
"Proposals can be accepted if at least one other (non-author) Stan developer endorses the final draft of the design document and there are no denials."
We can have “denials” and still merge it in.
There was a problem hiding this comment.
Right, I think we agree we don't want to word this as if each design doc required consensus. Nor do we (most of us at least, citing your Bob quote above) want a vetocracy, which I think is how it's worded now. How about,
"Design docs are a chance for the community to discuss and get into alignment on the pros and cons of the proposal. This means giving enough time for members of the community to review/comment/request changes on the proposal. After that time period (TODO: select a time period?) has ended, a proposal can be accepted if at least one other Stan developer endorses the proposal and merges it. Disagreements with merged proposals can be taken up via the SGB technical issue voting proposal as with other technical issues."
There was a problem hiding this comment.
For me here the key is both making sure issues are fully aired and discussed and everyone can be brought as on board as possible while still making forward progress the default.
There was a problem hiding this comment.
FWIW I am in favor of this rewording. It's essentially the same thing but does not use the word consensus and the added mention of going to a vote is also a plus.
There was a problem hiding this comment.
+1 from me too!
Yes, the original one wasn't true to the discussion and should definitely be changed.
(If people are allergic to the term "consensus" we don't have to use it.)
There was a problem hiding this comment.
And... thank you for the edit!
There was a problem hiding this comment.
Yay! Haha, I think that's a good way to put it - I do feel allergic to the term "consensus" 😂
I just replied to your comments. Just for clarification, it wasn't "agreed upon" by the people on the thread and what you quoted wasn't meant to be the delta. There's a tiny bit more from the suggestion from @bob-carpenter that gives more context:
I didn't read @bob-carpenter's comment to mean that's the only change to be made. (If it was, I'm sure he would have done it himself.) I incorporated the first bullet, but not the second. I'm not sure the second belongs in this doc. If it does, can someone suggest a good spot for it or edit it? |
|
Next steps, I’ll wait for additional comments and suggestions and then update the doc. |
I'm following up on this conversation on Discourse:
https://discourse.mc-stan.org/t/process-for-design-docs/
I edited the README.md to reflect a few things:
If any of this is unclear or isn't accomplished, please point it out or suggest changes.