From 7f70525e68877f85d2ac148ec8325d835bc054fb Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 10 Oct 2019 16:19:12 +0200 Subject: [PATCH 01/15] WEP0, a proposal for the WEP process 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. --- WEP0000_wep-proposal.rst | 228 +++++++++++++++++++++++++++++++++++++++ wep-template.rst | 46 ++++++++ 2 files changed, 274 insertions(+) create mode 100644 WEP0000_wep-proposal.rst create mode 100644 wep-template.rst diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst new file mode 100644 index 0000000..860351f --- /dev/null +++ b/WEP0000_wep-proposal.rst @@ -0,0 +1,228 @@ +:WEP-Number: 0000 +:Created: 2019-10-01 +:Last-Modified: 2019-10-01 +:Author: - Eric Holscher + - Sasha Romijn + - Samuel Wright + - Mikey Ariel +:Status: Draft +:Replaces: N/A +:Superceded-By: N/A + +WEP0000 - Initial Launch of the WEP Process +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Abstract +======== + +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. + +Motivation +========== + +When Write the Docs first started in 2013, it was a small collection of humans who were seeking a community of like-minded folks in Portland, Oregon. These folks named themselves **Documentarians**, and the community became our home to share knowledge and socialize with our peers from various roles, locations, and industries. + +Over the years, we have grown to a global community with multiple conferences, scores of meetups, and a robust Slack group with thousands of members. The conference teams converged and developed beyond anything that we imagined when we first started, and the Write the Docs organization has become just that -- an organization. + +During the past year it has become apparent, by talking to various long-term community members and by reviewing our current processes and policies, that there is a need for a formal system to manage changes to the community. We have multiple platforms where community members can interact, and we want to provide a way to communicate and engage the global community in decisions that will affect how the community is organized and moderated. + +We examined other open-source communities to see how they manage their governance and process changes, and we decided to propose the WEP system because we saw it was successful in multiple open-source communities, who contain a much larger user and contributor base and used similar systems for many years. We hope that laying the groundwork with this system will help Write the Docs scale globally with maximum transparency and collaboration. + +We believe that the WEP process will help facilitate open decision-making by being a public place to change and document governance for the whole community. Having our foundational documents, and the conversations that lead to them, available publicly will inform new and existing members of the community. Over time, we hope that the WEP repository will become the foundational set of policies that the community is built upon, with this document being the first act. + +Proposal +======== + +The WEP system consists of a dedicated `GitHub repository `_, which contains individual files that represent specific proposals to policies, processes, and programs in the community. The repository is public, and all WEPs are submitted and reviewed publicly by the entire community. + +What is a WEP? +-------------- + +WEP stands for Write the Docs Enhancement Proposal. A WEP is a document that provides process information to the Write the Docs community or that describes a new policy for the Write the Docs organization. + +WEPs describe **policies and processes** surrounding Write the Docs events and online community, and therefore require community consensus. For example, a WEP might propose a change to an organizational process, community policies, or the decision-making process itself. + +Scope of WEPs +------------- + +WEPs are generally intended for long-term policies that affect either a large number of community members, or that affect fewer but more significant segments of the community. + +Examples of topics that should use the WEP process: + +- Adjusting the structure of the Slack community to make it more accessible to new community members +- Policies about the structure of the Write the Docs organization +- Policy related to Slack team or channel guidelines +- Changes to the Code of Conduct (CoC) +- A grant policy to support conference attendees that need financial support +- A policy on how to balance various topics submitted to the Call for Proposals at the various Write the Docs conferences + +Examples of topics that are out of the scope of the WEP process: +- Requests to change CFP policies in a specific conference +- Requests to create a new Slack channel +- Specific CoC violation reports +- Requests to create a new meetup + +Topics that are out of scope for a WEP should be discussed in other community platforms, such as within the conference team, Slack team, or Code of Conduct team. The WEP team will direct out-of-scope pre-proposals to the relevant team in the rejection comments. + +Generally, WEPs do not contain the names of individual people, but rather references to teams in the Write the Docs organization. Similarly, they don’t contain fixed budget numbers, but instead guidelines for how to implement the budget. + +How to submit a WEP +------------------- + +Anyone from the community can submit a WEP! Here's how it works, and what to expect. + +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 `_. The updated name is intended to reflect the purpose of the team more accurately in the context of its duties for the community. + +WEP team + The **WEP team** is a new team that reviews WEP proposals for clarity and completeness. For the purpose of this WEP the team is initially composed of the Core Operations team, but in the the future will be open for other community members to join. + +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: + +#. `Pre-proposal`_ — Someone has an idea and they start collecting early input and feedback to see if it is within the scope of a WEP. This can be done informally, publicly or privately. + +#. `Draft submission and pre-review`_ — The WEP author writes a rough draft of the WEP and submits it in a pull request (PR) to the WEPs repository. The draft is pre-reviewed by an editor for style, formatting, and eligibility for the WEP process. If the WEP is pre-approved, it is accepted for discussion and the review period begins. + +#. `Community review, discussion, and updates`_ — During the review period, the WEP draft is discussed, improved, and updated based on incoming feedback from the community. Feedback is welcome from the whole community, as long as it arrives within the review period. + +#. `Final review and resolution`_ — At the end of the review period, the WEP is examined for **lazy consensus**. A lazy consensus means a situation where the community either provided feedback, approved the WEP explicitly, or ignored the WEP altogether. In some cases where consensus wasn't reached, the review period might be extended, but never shortened. + +#. `Implementation`_ — If the WEP is accepted, the processes or policies described in the WEP are implemented by the CoreOps team, the WEP author, or specific community members as defined in the WEP. + +The following sections describe each stage in more detail. + +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. + +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. + +Draft submission and pre-review +............................... + +A draft WEP must be submitted in a GitHub pull request to the `writethedocs/weps `_ repository, in the ``drafts/`` directory. If you need help with working with GitHub or creating a PR, please feel free to send an e-mail to support@writethedocs.org, and the Write the Docs team will help you get started. + +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. +- 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. + + +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. + +After the WEP is ready for the community review, the reviewer assigns the **ready-for-discussion** label to the PR. The CoreOps team is then responsible for distributing announcements of each WEP to the relevant community segment. For example, a WEP about meetups will be shared with the Meetup team for distribution between the meetup organizers. For some WEPs, community-wide announcements will be made on Slack or to the mailing list. + +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. + +If the review period ends without a clear consensus, but further discussion is still needed, the review period might be extended by the WEP team. The review period is never shorter than one month, but other WEPs can be submitted in the meantime, and multiple WEPs might be undergoing a community review simultaneously. + +During the community review period, the WEP goes through one or more iterations of feedback and updates. Community feedback is submitted in the form of comments to the PR, and the WEP author is responsible to update the WEP content in case the incoming feedback is accepted. + +All discussion on the WEP must happen on the PR in the form of comments in order to be considered as official feedback on the WEP. Of course external conversations can happen on other platforms, but the official record for a WEP discussion is only on the PR itself. If discussion happens on another platform, we recommend copying the most important points or the results of those discussions into the WEP comments. + +You must have a GitHub account to post comments to a PR. If you need help getting started with GitHub, email support@writethedocs and the WTD team will help you set up your account and get familiar with GitHub basics. + +Final review and resolution +........................... + +At the end of the community review period, the WEP is accepted if it meets the minimum criteria and received lazy consensus as described in the previous process stages. + +The WEP team reviews the final WEP content and if it is accepted, the team merges the PR, removes the **ready-for-discussion** flag, and moves the WEP to the ``accepted`` directory of the GitHub repository. + +Possible resolutions for a WEP are: + +Accepted + Reason: Community feedback was completed with lazy consensus achieved, and the WEP content is complete and follows the formatting guidelines. + 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. + Action: The WEP team moves the WEP to the ``rejected`` directory and merges the PR with a description of the rejection decision. + +Withdrawn + WEP author is no longer interested in pursuing the change, or no progress was made during the pre-review stage before the WEP was sent to community review. + Action: The WEP author moves the WEP moves the WEP to the ``withdrawn`` folder and merges the PR with a description of the withdrawal decision. + +If no community consensus was reached, the CoreOps team has the final authority to decide the resolution for a WEP. The CoreOps team is responsible to communicate their decision in the PR discussion and in community announcements as needed. + +Any community member can restart the WEP process on a rejected or withdrawn WEP in the future, by creating a new PR and updating the WEP according to the new information or ideas. If you are interested in restarting a WEP that was authored by someone else, we encourage you to contact the original author before you begin, in case they are interested in collaborating or have information that can help you in the process. + +Implementation +.............. + +After a WEP is accepted, the work outlined in the WEP must be done. For most WEPs, the CoreOps team is responsible to take the needed action or coordinate with other teams to take the need actions. + +For example, if this WEP is accepted, it means the system is now in place and the CoreOps team will publish the information to the community website and establish the WEP team, along with other related tasks that need to be done to implement the process in the community. + +Some WEPs might require specific community segments to implement the resolution, and such requirements are described in the WEPs directly. + +WEP format and style +-------------------- + +To make the authoring and reviewing process easier, WEPs must follow a common format and style. + +We use `reStructuredText `_ markup language for all WEPs, to align with the same markup that is used in all other Write the Doc documentation. + +In most cases, you can start by copying the `WEP template <../wep-template.rst>`_ and adding content as needed. The following sections describe the various sections of the template: + +.. AI - Make the template! + +File name +......... +The file name must follow the naming convention ``WEP[####]_[descriptive-but-short-title]``. For example, this WEP file is named ``WEP0000_wep-proposal``. In another example, a WEP to propose a new Slack channel naming convention might be named ``WEP0001_slack-channel-renaming``. + +Metadata +........ +The WEP file must begin with a header list of metadata fields, using the standard `RST field list `_ format. + +The field list usually includes the following fields: + +- ``:WEP-Number:`` - Number of the WEP, in running order in 4-digit format. Only use the number value, without the acronym **WEP**. For example, this WEP is numbered ``0000``. If the number is unknown or unassigned when you first create the WEP, you can leave this field blank and the number will be updated at the resolution stage. +- ``:Created:`` Date of initial creation, in the format YYYY-MM-DD. +- ``:Last-Modified:`` Date of the most recent changes to the WEP, in the format YYYY-MM-DD. +- ``:Author:`` - Full names of one or more authors of the WEP. Do not write email addresses or social media nicknames in this field. If the WEP is co-authored by multiple people, use a bulleted list similar to the header of this WEP. +- ``:Status:`` - Current status of the WEP. All WEPs begin with a ``Draft`` status, and the field changes with every stage in the WEP lifecycle. For example, ``Accepted``, ``Rejected``, ``Withdrawn``, ``Final``, or ``Superseded``. +- ``:Replaces:`` - Optional. If this WEP was created instead of a previous WEP that was rejected or withdrawn, list the number and title of the previous WEP. +- ``:Superceded-By:`` - Optional. If this WEP rejected or withdrawn and a newer WEP was submitted instead with updated content, list the number and title of the WEP that supercedes this WEP. + +Structure +......... + +Each WEP must contain the following sections: + +#. **Header.** Header with a list of metadata fields as described in this section. +#. **Title.** Short descriptive title of the WEP. The title must follow the naming convention ``WEP[#] - [Descriptive title]``. +#. **Abstract.** Short description of the topic that the WEP addresses. Use only 1-2 paragraphs and focus on the summary of the topic. +#. **Motivation.** Background information explaining why the existing processes or solutions need to change. +#. **Proposal.** Full description of the proposed change. This section can be as short or as long as needed, including explanations or alternatives if applicable. Use sub-headings to divide the proposal section if it contains a large amount of text. +#. **Copyright.** Boilerplate license statement for the WEP. All WEPs must be published under the **Creative Commons CC-BY 4.0** license. This boilerplate text must be used as-is without alterations. + +If you are unsure whether the WEP you are authoring is structured correctly, you can submit it as a WIP draft and ask for help from the WEP team, or email us at support@writethedocs.org and we will be happy to help you with the preparation. + +Acknowledgments +--------------- + +The WEP process is based on the `Django DEP `_ process, which in turn was based on the `Python PEP `_ process. We would like to thank the Python and Django communities for providing these open-source resources publicly and freely to help other communities. + +Copyright +========= + +This document is published under the `Creative Commons CC-BY 4.0 Attribution `_ license. diff --git a/wep-template.rst b/wep-template.rst new file mode 100644 index 0000000..b857755 --- /dev/null +++ b/wep-template.rst @@ -0,0 +1,46 @@ + +.. Template instructions: + +.. 0 Copy this file and rename it according to WEP filename convention: [WEP####-short-descriptive-name.rst] +.. 1. Replace all values in square brackets [] with actual values. +.. 2. Remove optional fields that you do not need. +.. 3. Follow reStructured Text markup conventions: http://docutils.sourceforge.net/rst.html +.. 4. Remove these instructions before submitting the PR. +.. 5. Submit the WEP as a PR and make sure it follows the guidelines of WEP0000: [URL] + +.. For questions and help in creating the WEP, email support@writethedocs.org + +:WEP-Number: [####] +:Created: [YYYY-MM-DD] +:Last-Modified: [YYYY-MM-DD] +:Author: - [FULL NAME 1] + - [FULL NAME 2] + - ... + - ... +:Status: Draft +:Replaces: [OPTIONAL] +:Superceded-By: [OPTIONAL] + +WEP[####] - [Short but descriptive title] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Abstract +======== + +[Short summary of the WEP purpose. 1-2 paragraphs maximum. This is the TL;DR.] + +Motivation +========== + +[Background information explaining why the existing processes or solutions need to change. 2-3 paragraphs maximum.] + +Proposal +======== + +[Full description of the proposed change. This section can be as short or as long as needed, including explanations or alternatives if applicable. Use sub-headings to divide the proposal section if it contains a large amount of text.] + +Copyright +========= +[DO NOT CHANGE OR REMOVE THIS SECTION. Mandatory license boilerplate text. Remove only this line.] + +This document is published under the `Creative Commons CC-BY 4.0 Attribution `_ license. From 26588a5357614163c96fceaa6aba75d03ecf4d25 Mon Sep 17 00:00:00 2001 From: Sasha Romijn Date: Wed, 13 Nov 2019 13:41:39 +0100 Subject: [PATCH 02/15] Remove obsolete action item. Co-Authored-By: Daniel D. Beck --- WEP0000_wep-proposal.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index 860351f..eba9888 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -183,7 +183,6 @@ We use `reStructuredText `_ markup lan In most cases, you can start by copying the `WEP template <../wep-template.rst>`_ and adding content as needed. The following sections describe the various sections of the template: -.. AI - Make the template! File name ......... From d0b7ff541590c8108e38ff2d919349bcff0fe070 Mon Sep 17 00:00:00 2001 From: Sasha Romijn Date: Wed, 13 Nov 2019 13:42:47 +0100 Subject: [PATCH 03/15] Fix email address typo. --- WEP0000_wep-proposal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index eba9888..c4d24ad 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -138,7 +138,7 @@ During the community review period, the WEP goes through one or more iterations All discussion on the WEP must happen on the PR in the form of comments in order to be considered as official feedback on the WEP. Of course external conversations can happen on other platforms, but the official record for a WEP discussion is only on the PR itself. If discussion happens on another platform, we recommend copying the most important points or the results of those discussions into the WEP comments. -You must have a GitHub account to post comments to a PR. If you need help getting started with GitHub, email support@writethedocs and the WTD team will help you set up your account and get familiar with GitHub basics. +You must have a GitHub account to post comments to a PR. If you need help getting started with GitHub, email support@writethedocs.org and the WTD team will help you set up your account and get familiar with GitHub basics. Final review and resolution ........................... From b44fc59f6260a615ad5bf315c783055a11063c37 Mon Sep 17 00:00:00 2001 From: Sasha Romijn Date: Wed, 13 Nov 2019 13:44:06 +0100 Subject: [PATCH 04/15] Clarify review period length earlier on. --- WEP0000_wep-proposal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index c4d24ad..4120cca 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -87,7 +87,7 @@ At a very high level, the WEP submission process includes the following stages: #. `Pre-proposal`_ — Someone has an idea and they start collecting early input and feedback to see if it is within the scope of a WEP. This can be done informally, publicly or privately. -#. `Draft submission and pre-review`_ — The WEP author writes a rough draft of the WEP and submits it in a pull request (PR) to the WEPs repository. The draft is pre-reviewed by an editor for style, formatting, and eligibility for the WEP process. If the WEP is pre-approved, it is accepted for discussion and the review period begins. +#. `Draft submission and pre-review`_ — The WEP author writes a rough draft of the WEP and submits it in a pull request (PR) to the WEPs repository. The draft is pre-reviewed by an editor for style, formatting, and eligibility for the WEP process. If the WEP is pre-approved, it is accepted for discussion and the 30-day review period begins. #. `Community review, discussion, and updates`_ — During the review period, the WEP draft is discussed, improved, and updated based on incoming feedback from the community. Feedback is welcome from the whole community, as long as it arrives within the review period. From 1cea2d68d7c7aab42db25398539eea4b49934cfd Mon Sep 17 00:00:00 2001 From: Sasha Romijn Date: Wed, 13 Nov 2019 13:45:21 +0100 Subject: [PATCH 05/15] Fix grammar error. --- WEP0000_wep-proposal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index 4120cca..87d301a 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -200,7 +200,7 @@ The field list usually includes the following fields: - ``:Author:`` - Full names of one or more authors of the WEP. Do not write email addresses or social media nicknames in this field. If the WEP is co-authored by multiple people, use a bulleted list similar to the header of this WEP. - ``:Status:`` - Current status of the WEP. All WEPs begin with a ``Draft`` status, and the field changes with every stage in the WEP lifecycle. For example, ``Accepted``, ``Rejected``, ``Withdrawn``, ``Final``, or ``Superseded``. - ``:Replaces:`` - Optional. If this WEP was created instead of a previous WEP that was rejected or withdrawn, list the number and title of the previous WEP. -- ``:Superceded-By:`` - Optional. If this WEP rejected or withdrawn and a newer WEP was submitted instead with updated content, list the number and title of the WEP that supercedes this WEP. +- ``:Superceded-By:`` - Optional. If this WEP is rejected or withdrawn and a newer WEP was submitted instead with updated content, list the number and title of the WEP that supercedes this WEP. Structure ......... From decfc9d00991df765cd4f51984c107ad0b7c49ed Mon Sep 17 00:00:00 2001 From: Sasha Romijn Date: Wed, 27 Nov 2019 17:07:03 +0100 Subject: [PATCH 06/15] Update wep-template.rst Co-Authored-By: Daniel D. Beck --- wep-template.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wep-template.rst b/wep-template.rst index b857755..ec2fe7a 100644 --- a/wep-template.rst +++ b/wep-template.rst @@ -27,7 +27,7 @@ WEP[####] - [Short but descriptive title] Abstract ======== -[Short summary of the WEP purpose. 1-2 paragraphs maximum. This is the TL;DR.] +[Short summary of the WEP purpose. 100 words maximum. This is the TL;DR.] Motivation ========== From 574c54187c290339fb5bab37cbde1cebbed307fc Mon Sep 17 00:00:00 2001 From: Sasha Romijn Date: Wed, 27 Nov 2019 17:22:28 +0100 Subject: [PATCH 07/15] Update wep-template.rst Co-Authored-By: Daniel D. Beck --- wep-template.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wep-template.rst b/wep-template.rst index ec2fe7a..54ff138 100644 --- a/wep-template.rst +++ b/wep-template.rst @@ -32,7 +32,7 @@ Abstract Motivation ========== -[Background information explaining why the existing processes or solutions need to change. 2-3 paragraphs maximum.] +[Background information explaining why the existing processes or solutions need to change. 500 words maximum.] Proposal ======== From d7b581ca2d7e7bf258b33856bc017a97e0737be1 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Wed, 4 Dec 2019 14:09:03 +0100 Subject: [PATCH 08/15] Update WEP0000_wep-proposal.rst Co-Authored-By: Mike Jang --- WEP0000_wep-proposal.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index 87d301a..d2c421d 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -102,7 +102,11 @@ 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. -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. +If you have an idea for a WEP: + + - Discuss the idea in a public forum such as the Write the Docs Slack. + - Gather initial community feedback to enhance your WEP. + - Make sure your idea applies to the entire community and not just yourself. 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. From 14e36069802fa56e9e8b73cf83e423183bda128f Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 4 Dec 2019 14:16:10 +0100 Subject: [PATCH 09/15] Address feedback from Mike: attempt to clarify process more --- WEP0000_wep-proposal.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index d2c421d..b26a270 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -76,14 +76,14 @@ Anyone from the community can submit a WEP! Here's how it works, and what to exp 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 `_. The updated name is intended to reflect the purpose of the team more accurately in the context of its duties for the community. + There are several references 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 `_. The updated name is intended to reflect the purpose of the team more accurately in the context of its duties for the community. WEP team The **WEP team** is a new team that reviews WEP proposals for clarity and completeness. For the purpose of this WEP the team is initially composed of the Core Operations team, but in the the future will be open for other community members to join. 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: +At a high level, the WEP submission process includes the following stages: #. `Pre-proposal`_ — Someone has an idea and they start collecting early input and feedback to see if it is within the scope of a WEP. This can be done informally, publicly or privately. @@ -117,24 +117,23 @@ A draft WEP must be submitted in a GitHub pull request to the `writethedocs/weps 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. +- The WEP's proposed change must be specific and the resulting action clear. +- The 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 WEP team. - 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. - 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. +The WEP team 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. After the WEP is ready for the community review, the reviewer assigns the **ready-for-discussion** label to the PR. The CoreOps team is then responsible for distributing announcements of each WEP to the relevant community segment. For example, a WEP about meetups will be shared with the Meetup team for distribution between the meetup organizers. For some WEPs, community-wide announcements will be made on Slack or to the mailing list. 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. +The standard community review period for a WEP is **30 days**. The WEP is decided on by a process called **lazy consensus**. This means that community members either provide feedback, approve the WEP explicitly, or ignore the WEP. If the review period ends without a clear consensus, but further discussion is still needed, the review period might be extended by the WEP team. The review period is never shorter than one month, but other WEPs can be submitted in the meantime, and multiple WEPs might be undergoing a community review simultaneously. From 092f1d4eea3cbcb56456b4b2062c7e2cbec08965 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Wed, 4 Dec 2019 16:53:39 +0100 Subject: [PATCH 10/15] Update WEP0000_wep-proposal.rst Co-Authored-By: Mikey Ariel --- WEP0000_wep-proposal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index b26a270..2d2bfc9 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -100,7 +100,7 @@ The following sections describe each stage in more detail. 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. +The WEP process begins with an idea for Write the Docs. It is highly recommended that a single WEP contain a single key proposal or idea. If you have an idea for a WEP: From 77702667b39f4c78629e848d8a776450239999dc Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Wed, 4 Dec 2019 16:53:57 +0100 Subject: [PATCH 11/15] Update WEP0000_wep-proposal.rst Co-Authored-By: Mikey Ariel --- WEP0000_wep-proposal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index 2d2bfc9..a4dcf34 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -122,7 +122,7 @@ The WEP draft must follow these guidelines: - 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. +- The PR is tagged with a **draft** label in GitHub, to indicate that it is in a draft state and is ready for pre-review. 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. From 5d71e61f7ade2fac2bfe5963c6fdefbe31759dbe Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Wed, 11 Dec 2019 14:48:48 +0100 Subject: [PATCH 12/15] Update WEP0000_wep-proposal.rst Co-Authored-By: Mikey Ariel --- WEP0000_wep-proposal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index a4dcf34..64b1735 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -157,7 +157,7 @@ Accepted 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. + Reason: Community feedback led to disagreements that prevented the WEP from reaching consensus, or the original goal of the WEP is no longer considered an improvement to the community. Action: The WEP team moves the WEP to the ``rejected`` directory and merges the PR with a description of the rejection decision. Withdrawn From 5c015ef8282687566e1dc3aa28ced5d821cbcd57 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 12 Dec 2019 12:49:21 +0100 Subject: [PATCH 13/15] Update WEP0000_wep-proposal.rst Co-Authored-By: Mikey Ariel --- WEP0000_wep-proposal.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index 64b1735..bdacd5a 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -108,7 +108,9 @@ If you have an idea for a WEP: - Gather initial community feedback to enhance your WEP. - Make sure your idea applies to the entire community and not just yourself. -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. +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. + +After the WEP is submitted, additional supporters of the WEP can add their votes in the community review round, but only the co-authors will implement feedback in order to simplify the editing process. Draft submission and pre-review ............................... From dd548b806701078f10109fa35c17f661c194b1c2 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 12 Dec 2019 16:45:58 +0100 Subject: [PATCH 14/15] Update WEP0000_wep-proposal.rst Co-Authored-By: Mikey Ariel --- WEP0000_wep-proposal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index bdacd5a..ace8c88 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -9,7 +9,7 @@ :Replaces: N/A :Superceded-By: N/A -WEP0000 - Initial Launch of the WEP Process +WEP0 - Initial Launch of the WEP Process ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Abstract From 0287aff4d13661115e51522e6a8ea3bdc984fb41 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 12 Dec 2019 16:47:07 +0100 Subject: [PATCH 15/15] Apply suggestions from code review Co-Authored-By: Mikey Ariel --- WEP0000_wep-proposal.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/WEP0000_wep-proposal.rst b/WEP0000_wep-proposal.rst index ace8c88..cc2a873 100644 --- a/WEP0000_wep-proposal.rst +++ b/WEP0000_wep-proposal.rst @@ -192,7 +192,8 @@ In most cases, you can start by copying the `WEP template <../wep-template.rst>` File name ......... The file name must follow the naming convention ``WEP[####]_[descriptive-but-short-title]``. For example, this WEP file is named ``WEP0000_wep-proposal``. In another example, a WEP to propose a new Slack channel naming convention might be named ``WEP0001_slack-channel-renaming``. - + +Note that the full file name must contain lead-in digits to enable auto-sorting of files and URLs. The title of the WEP can use the short name. Metadata ........ The WEP file must begin with a header list of metadata fields, using the standard `RST field list `_ format. @@ -213,7 +214,7 @@ Structure Each WEP must contain the following sections: #. **Header.** Header with a list of metadata fields as described in this section. -#. **Title.** Short descriptive title of the WEP. The title must follow the naming convention ``WEP[#] - [Descriptive title]``. +#. **Title.** Short descriptive title of the WEP. The title must follow the naming convention ``WEP[#] - [Descriptive title]``. You can use the short numbering format in the title, such as **WEP0**. #. **Abstract.** Short description of the topic that the WEP addresses. Use only 1-2 paragraphs and focus on the summary of the topic. #. **Motivation.** Background information explaining why the existing processes or solutions need to change. #. **Proposal.** Full description of the proposed change. This section can be as short or as long as needed, including explanations or alternatives if applicable. Use sub-headings to divide the proposal section if it contains a large amount of text.