-
Notifications
You must be signed in to change notification settings - Fork 3
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
WEP0, a proposal for the WEP process #1
Conversation
This is the first Write the Docs Enhancement Proposal (WEP), which introduces the WEP process itself and proposes to implement it in the Write the Docs community. The WEP process enables anyone from the community to propose process and policy changes to the community. The community then reviews the proposed change and if the change is accepted, the policy or process change is implemented in the community. This "meta-WEP" follows the WEP process to show how the process works and to help the community learn how to use it. Please read below and comment.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good to me.
meta-issue: there's no slack channel yet to discuss it. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm really excited that this is happening. Thank you for starting this!
Overall, I'm happy with the direction of this proposal. I've left a few comments and suggestions, mostly aimed at clearing up some points where I thought things were unclear or unspecific. Thank you again!
WEP0000_wep-proposal.rst
Outdated
- Content format must follow the WEP style as described in the **WEP format and style** section. This includes language, grammar, structure, and markup. The PR might be blocked until proper formatting rules are applied. | ||
- The WEP content is complete. If you want to submit a Work in Progress (WIP) draft before it is ready for pre-review, you can mark the PR as ``WIP`` and the review team will wait until the draft is ready. | ||
- **Allow edits from maintainers** option is selected. This helps the reviewer merge your WEP draft if it is accepted. | ||
- The PR is tagged with a **draft** flag, to indicate that it is in a draft state and is ready for pre-review. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is "tagged" here? Is this opening the PR in GitHub's draft status, a label on the PR, text in the WEP, or something else?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My understanding is this: https://github.com/writethedocs/weps/pull/1/files#diff-f47194e85dd085426bc962ab2fd3baf6R202
A GH action to parse that and set labels would be super cute.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think that it boils down to labels that are manually assigned, rather than a draft state. Let's reword this to align with GH terminology.
WEP0000_wep-proposal.rst
Outdated
Action: The WEP team merges the PR and stores the WEP in the ``accepted`` directory. | ||
|
||
Rejected | ||
Reason: Community feedback led to disagreements about the WEP that cannot be resolved, or the original goal of the WEP is no longer considered an improvement to the community. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
no longer considered an improvement to the community
I think the passive voice here makes it hard to understand the process. Is this meant to be a characterization of the review discussion (e.g., community feedback leads to a negative consensus that the WEP should be rejected)? Or is this an independent conclusion of the WEP team (e.g., the WEP team reviews the final text and makes its own decision on whether its an improvement to the community)?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The former, I'd say.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed that I think we meant the former. I guess we should have a state that is "rejected by the powers that be" -- perhaps Vetoed
, which makes this more explicit?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not comfortable with a Veto option here, since it seems a bit contradictory to the consensus idea. I made a suggestion to reword the text to make it more explicit, maybe it'll solve the question.
Consider looking at the pattern used at https://aip.dev/ if you have not already - similar to what you are trying to do here, and there may be some aspects of AIP you can reuse. |
Co-Authored-By: Daniel D. Beck <[email protected]>
Co-Authored-By: Daniel D. Beck <[email protected]>
Co-Authored-By: Daniel D. Beck <[email protected]>
WEP0000_wep-proposal.rst
Outdated
The WEP process and system are administered by the following teams: | ||
|
||
Core Operations team | ||
There are several reference in this WEP to the **core operations (CoreOps) team**. This team is currently known as the **core team** and the team description can be found on the `Core team page <https://www.writethedocs.org/team/#core-team>`_. The updated name is intended to reflect the purpose of the team more accurately in the context of its duties for the community. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
s/reference/references/
WEP0000_wep-proposal.rst
Outdated
|
||
Note that the process to join and leave teams is out of scope of this WEP and will be handled in a future WEP. | ||
|
||
At a very high level, the WEP submission process includes the following stages: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should this be written in a more active voice, e.g. If you have an idea for , take the following steps:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is more the definition of the process, I think we'll grow a "how to" guide in the future as we get more process around it.
WEP0000_wep-proposal.rst
Outdated
Pre-proposal | ||
............ | ||
|
||
The WEP process begins with a new idea for Write the Docs. It is highly recommended that a single WEP contain a single key proposal or new idea. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does it have to be a "new idea"?
If the WEP contains multiple proposals, I think that would come out in the discussion.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think we're going to judge things by any new-ness quality, it's more just a turn of phrase. Perhaps "process update" is more explicit?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In the tech writing world, the word "new" is usually redundant. I vote we clean it up and just say "idea".
WEP0000_wep-proposal.rst
Outdated
|
||
To help prepare the WEP draft, we encourage community members to discuss the idea publicly, for example in the Slack group, and gather initial community feedback before writing a full WEP. Public discussions on pre-proposals also help to make sure the idea is applicable to the entire community and not just to the author. | ||
|
||
A WEP can be co-authored by more than one community member, but we recommend keeping the number of co-authors small and choosing a representative who will submit the PR to the WEPs repository on behalf of the co-authors. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we recommend keeping the number of co-authors small
I'm not sure we should even mention this. But if you think it's important, I'd like an explanation.
If I were a WEP author, I'd want to have as many "co-sponsors" as possible.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There is a difference between "co-authors" and "co-sponsors". Co-authors are actively creating the WEP before it's submitted to community discussion, while co-sponsors should be enlisted during the discussion phase. The goal here is to distinguish ownership of the WEP creation and feedback implementation, and you probably don't want 10 people authoring the same WEP for logistical reasons :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we stole this from the PEP process, but I think the goal is to have a couple people responsible for shepherding it. If 5 people come together it becomes hard to figure out who is in charge and can make decisions. I think smaller is definitely better in terms of the proposal team, but not in terms of who looks at and reviews it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Appreciate the explanation. Then maybe s/on behalf of the co-authors/on behalf of all supporters of the WEP/
(The current text, to me, implies that support is limited to the authors)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wrote in a suggestion to expand this paragraph and differentiate between authors and supporters. Feel free to edit/adapt as needed.
WEP0000_wep-proposal.rst
Outdated
|
||
The WEP draft must follow these guidelines: | ||
|
||
- WEP is actionable and implementable. The proposed change must be specific and the resulting action clear. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd leave out "WEP is actionable and implementable"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed, it's a bit of a weird sentence, the second one is more clear 👍
WEP0000_wep-proposal.rst
Outdated
The WEP draft must follow these guidelines: | ||
|
||
- WEP is actionable and implementable. The proposed change must be specific and the resulting action clear. | ||
- WEP fits the scope of the WEP process, as described in **Scope of WEPs**. WEPs that are out of scope of the process will be rejected by the reviewer. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
s/reviewer/WEP team/
(since anyone can review a PR, we should be specific)
WEP0000_wep-proposal.rst
Outdated
|
||
After the pull request for the WEP draft is submitted, a WEP team member reviews the pull request to make sure it adheres to the guidelines. If the WEP is clearly not ready, the reviewer might reject the pull request and ask the author to submit a new WEP after the problems have been fixed. | ||
|
||
The reviewer does not vote on the proposed change itself, and only reviews the WEP for scope compliance, format, and completeness. The pre-review period is usually one week, but might change based on the scope of the pre-review feedback and the availability of the author to implement changes. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That suggests the "reviewer" is different from the "WEP team", which upon first reading contradicts earlier text
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The term "reviewer" is defined in the first paragraph as "a WEP team member... reviews"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've added WEP team reviewer
to be more explicit, which seems fine.
WEP0000_wep-proposal.rst
Outdated
Community review, discussion, and updates | ||
......................................... | ||
|
||
The standard community review period for a WEP is **30 days**. The WEP is reviewed by a process called **lazy consensus**. This means that community members either provide feedback, approve the WEP explicitly, or ignore the WEP. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The "community review" is different from the "reviewer" who looks at scope and compliance? The redundancy in these terms is confusing me
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yea, the WEP team does the initial review for acceptance, then the wider community will look at it and have input. There are effectively 2 stages of review.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've changed the language to decided on
, since reviewed here I agree is ambiguous.
Co-Authored-By: Mike Jang <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the feedback Mike -- I've pushed up a few clarifications.
WEP0000_wep-proposal.rst
Outdated
|
||
Note that the process to join and leave teams is out of scope of this WEP and will be handled in a future WEP. | ||
|
||
At a very high level, the WEP submission process includes the following stages: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is more the definition of the process, I think we'll grow a "how to" guide in the future as we get more process around it.
WEP0000_wep-proposal.rst
Outdated
Pre-proposal | ||
............ | ||
|
||
The WEP process begins with a new idea for Write the Docs. It is highly recommended that a single WEP contain a single key proposal or new idea. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think we're going to judge things by any new-ness quality, it's more just a turn of phrase. Perhaps "process update" is more explicit?
WEP0000_wep-proposal.rst
Outdated
|
||
The WEP draft must follow these guidelines: | ||
|
||
- WEP is actionable and implementable. The proposed change must be specific and the resulting action clear. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed, it's a bit of a weird sentence, the second one is more clear 👍
WEP0000_wep-proposal.rst
Outdated
|
||
After the pull request for the WEP draft is submitted, a WEP team member reviews the pull request to make sure it adheres to the guidelines. If the WEP is clearly not ready, the reviewer might reject the pull request and ask the author to submit a new WEP after the problems have been fixed. | ||
|
||
The reviewer does not vote on the proposed change itself, and only reviews the WEP for scope compliance, format, and completeness. The pre-review period is usually one week, but might change based on the scope of the pre-review feedback and the availability of the author to implement changes. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've added WEP team reviewer
to be more explicit, which seems fine.
WEP0000_wep-proposal.rst
Outdated
Community review, discussion, and updates | ||
......................................... | ||
|
||
The standard community review period for a WEP is **30 days**. The WEP is reviewed by a process called **lazy consensus**. This means that community members either provide feedback, approve the WEP explicitly, or ignore the WEP. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yea, the WEP team does the initial review for acceptance, then the wider community will look at it and have input. There are effectively 2 stages of review.
WEP0000_wep-proposal.rst
Outdated
Community review, discussion, and updates | ||
......................................... | ||
|
||
The standard community review period for a WEP is **30 days**. The WEP is reviewed by a process called **lazy consensus**. This means that community members either provide feedback, approve the WEP explicitly, or ignore the WEP. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've changed the language to decided on
, since reviewed here I agree is ambiguous.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some suggestions, some discussions resolved, and other beasts :)
WEP0000_wep-proposal.rst
Outdated
- Content format must follow the WEP style as described in the **WEP format and style** section. This includes language, grammar, structure, and markup. The PR might be blocked until proper formatting rules are applied. | ||
- The WEP content is complete. If you want to submit a Work in Progress (WIP) draft before it is ready for pre-review, you can mark the PR as ``WIP`` and the review team will wait until the draft is ready. | ||
- **Allow edits from maintainers** option is selected. This helps the reviewer merge your WEP draft if it is accepted. | ||
- The PR is tagged with a **draft** flag, to indicate that it is in a draft state and is ready for pre-review. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think that it boils down to labels that are manually assigned, rather than a draft state. Let's reword this to align with GH terminology.
WEP0000_wep-proposal.rst
Outdated
Action: The WEP team merges the PR and stores the WEP in the ``accepted`` directory. | ||
|
||
Rejected | ||
Reason: Community feedback led to disagreements about the WEP that cannot be resolved, or the original goal of the WEP is no longer considered an improvement to the community. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not comfortable with a Veto option here, since it seems a bit contradictory to the consensus idea. I made a suggestion to reword the text to make it more explicit, maybe it'll solve the question.
Co-Authored-By: Mikey Ariel <[email protected]>
Co-Authored-By: Mikey Ariel <[email protected]>
Co-Authored-By: Mikey Ariel <[email protected]>
Co-Authored-By: Mikey Ariel <[email protected]>
Co-Authored-By: Mikey Ariel <[email protected]>
Co-Authored-By: Mikey Ariel <[email protected]>
Feels like this is ready to be merged. I know we'll have to continue to evolve our approaches as we implement this new system, but I'm confident it will be better than what we're doing now :) Excited for a whole new world 🎉 |
This is the first Write the Docs Enhancement Proposal (WEP), which introduces the WEP process itself and proposes to implement it in the Write the Docs community.
The WEP process enables anyone from the community to propose process and policy changes to the community. The community then reviews the proposed change and if the change is accepted, the policy or process change is implemented in the community.
This "meta-WEP" follows the WEP process to show how the process works and to help the community learn how to use it.
Please read below and give us feedback to the process we're proposing!
Proposed WEP Timeline