slep000, slep workflow

slep000/proposal.rst

@@ -0,0 +1,270 @@
+.. _slep_000:
+
+==============================
+SLEP000: SLEP and its wofkflow
+==============================
+
+:Author: Adrin Jalali
+:Status: Draft
+:Type: Process
+:Created: 2020-02-13
+
+Abstract
+########
+
+This SLEP specifies details related to SLEP submission, review, and acceptance
+process.
+
+Motivation
+##########
+
+Without a predefined workflow, the discussions around a SLEP can be long and
+frustrating for both the author and the reviewers. The lack of a known workflow
+also results in the SLEPs to take months (if not years) before it is accepted
+as ``Draft``. The purpose of this SLEP is to lubricate and ease the
+process of working on a SLEP, and make it a more enjoyable and productive
+experience.
+
+
+What is a SLEP?
+###############
+
+SLEP stands for Scikit-Learn Enhancement Proposal. A SLEP is a design document
+providing information to the scikit-learn community, or describing a new
+feature for scikit-learn or its processes or environment. The SLEP should
+provide a concise technical specification of the feature and a rationale for
+the feature.
+
+We intend SLEPs to be the primary mechanisms for proposing major new features,
+for collecting community input on an issue, and for documenting the design
+decisions that have gone into scikit-learn. The SLEP author is responsible for
+building consensus within the community and documenting dissenting opinions.
+
+Because the SLEPs are maintained as text files in a versioned repository, their
+revision history is the historical record of the feature proposal.
+
+SLEP Audience
+#############
+
+The typical primary audience for SLEPs are the core developers of
+``scikit-learn`` and technical committee, as well as contributors to the
+project. However, these documents also serve the purpose of documenting the
+changes and decisions to help users understand the changes and why they are
+made.
+
+The proposal should be submitted as a draft SLEP via a GitHub pull request to a
+``slepXXX`` directory with the name ``proposal.rst`` where ``XXX`` is an
+appropriately assigned three-digit number (e.g., ``slep000/proposal.rst``). The
+draft must use the SLEP — Template and Instructions file.
+
+Once the PR for the SLEP is in place, a post should be made to the mailing list
+containing the sections up to “Backward compatibility”, with the purpose of
+limiting discussion there to usage and impact. Discussion on the pull request
+will have a broader scope, also including details of implementation.
+
+At the earliest convenience, the PR should be merged (regardless of whether it
+is accepted during discussion). Additional PRs may be made by the champions to
+update or expand the SLEP, or by maintainers to set its status, discussion URL,
+etc.
+
+Standards Track SLEPs consist of two parts, a design document and a reference
+implementation. It is generally recommended that at least a prototype
+implementation be co-developed with the SLEP, as ideas that sound good in
+principle sometimes turn out to be impractical when subjected to the test of
+implementation. Often it makes sense for the prototype implementation to be
+made available as PR to the scikit-learn repo (making sure to appropriately
+mark the PR as a WIP).
+
+SLEP Types
+##########
+
+There are three kinds of SLEPs:
+
+1. A Standards Track SLEP describes a new feature or implementation for
+scikit-learn.
+
+2. An Informational SLEP describes a scikit-learn design issue, or provides
+general guidelines or information to the scikit-learn community, but does not
+propose a new feature. Informational SLEPs do not necessarily represent a
+scikit-learn community consensus or recommendation, so users and implementers
+are free to ignore Informational SLEPs or follow their advice.
+
+3. A Process SLEP describes a process surrounding scikit-learn, or proposes a
+change to (or an event in) a process. Process SLEPs are like Standards Track
+SLEPs but apply to areas other than the scikit-learn library itself. They may
+propose an implementation, but not to scikit-learn’s codebase; they require
+community consensus. Examples include procedures, guidelines, changes to the
+decision-making process, and changes to the tools or environment used in
+scikit-learn development. Any meta-SLEP is also considered a Process SLEP.
+
+
+SLEP Workflow
+#############
+
+A SLEP starts with an idea, which usually is discussed in an issue or a pull
+request on the main repo before submitting a SLEP. It is generally a good idea
+for the author of the SLEP to gauge the viability and the interest of the
+community before working on a SLEP, mostly to save author's time.
+
+A SLEP must have one or more champions: people who write the SLEP following the
+SLEP template, shepherd the discussions around it, and seek consensus in the
+community.
+
+Review and Resolution
+---------------------
+
+SLEPs are discussed on the mailing list or the PRs modifying the SLEP. The
+possible paths of the status of SLEPs are as follows:
+
+.. image:: pep-0001-process_flow.png
+   :alt: SLEP process flow diagram
+
+All SLEPs should be created with the ``Draft`` status.
+
+Eventually, after discussion, there may be a consensus that the SLEP should be
+accepted – see the next section for details. At this point the status becomes
+``Accepted``.
+
+Once a SLEP has been ``Accepted``, the reference implementation must be
+completed. When the reference implementation is complete and incorporated into
+the main source code repository, the status will be changed to ``Final``.
+
+To allow gathering of additional design and interface feedback before
+committing to long term stability for a language feature or standard library
+API, a SLEP may also be marked as ``Provisional``. This is short for
+“Provisionally Accepted”, and indicates that the proposal has been accepted for
+inclusion in the reference implementation, but additional user feedback is
+needed before the full design can be considered ``Final``. Unlike regular
+accepted SLEPs, provisionally accepted SLEPs may still be ``Rejected`` or
+``Withdrawn`` even after the related changes have been included in a
+scikit-learn release.
+
+Wherever possible, it is considered preferable to reduce the scope of a
+proposal to avoid the need to rely on the ``Provisional`` status (e.g. by
+deferring some features to later SLEPs), as this status can lead to version
+compatibility challenges in the wider scikit-learn ecosystem.
+
+A SLEP can also be assigned status ``Deferred``. The SLEP author or a core
+developer can assign the SLEP this status when no progress is being made on the
+SLEP.
+
+A SLEP can also be ``Rejected``. Perhaps after all is said and done it was not
+a good idea. It is still important to have a record of this fact. The
+``Withdrawn`` status is similar; it means that the SLEP author themselves has
+decided that the SLEP is actually a bad idea, or has accepted that a competing
+proposal is a better alternative.
+
+When a SLEP is ``Accepted``, ``Rejected``, or ``Withdrawn``, the SLEP should be
+updated accordingly. In addition to updating the status field, at the very
+least the ``Resolution`` header should be added with a link to the relevant
+thread in the mailing list archives or where the discussion happened.
+
+SLEPs can also be ``Superseded`` by a different SLEP, rendering the original
+obsolete. The ``Replaced-By`` and ``Replaces`` headers should be added to the
+original and new SLEPs respectively.
+
+``Process`` SLEPs may also have a status of ``Active`` if they are never meant
+to be completed, e.g. SLEP 1 (this SLEP).
+
+How a SLEP becomes Accepted
+---------------------------
+
+A SLEP is ``Accepted`` by the voting mechanism defined in the governance model.
+We need a concrete way to tell whether consensus has been reached. When you
+think a SLEP is ready to accept, create a PR changing the status of the SLEP to
+``Accepted``, then send an email to the scikit-learn mailing list with a
+subject like:
+
+    Proposal to accept SLEP #<number>: <title>
+
+In the body of your email, you should:
+
+- link to the latest version of the SLEP, and a link to the PR accepting the
+  SLEP.
+
+- briefly describe any major points of contention and how they were resolved,
+
+- include a sentence like: “The vote will be closed in a month.”
+
+Generally the SLEP author will be the one to send this email, but anyone can do
+it; the important thing is to make sure that everyone knows when a SLEP is on
+the verge of acceptance, and give them a final chance to respond.
+
+In general, the goal is to make sure that the community has consensus, not
+provide a rigid policy for people to try to game. When in doubt, err on the
+side of asking for more feedback and looking for opportunities to compromise.
+
+If the final comment and voting period passes with the required majority, then
+the SLEP can officially be marked ``Accepted``. The ``Resolution`` header
+should link to the PR accepting the SLEP.
+
+If the vote does not achieve a required majority, then the SLEP remains in
+``Draft`` state, discussion continues as normal, and it can be proposed for
+acceptance again later once the objections are resolved.
+
+In unusual cases, with the request of the author, the scikit-learn technical
+committee may be asked to decide whether a controversial SLEP is ``Accepted``.
+
+Maintenance
+-----------
+
+In general, Standards track SLEPs are no longer modified after they have
+reached the ``Final`` state as the code and project documentation are
+considered the ultimate reference for the implemented feature. However,
+finalized Standards track SLEPs may be updated as needed.
+
+Process SLEPs may be updated over time to reflect changes to development
+practices and other details. The precise process followed in these cases will
+depend on the nature and purpose of the SLEP being updated.
+
+Format and Template
+-------------------
+
+SLEPs are UTF-8 encoded text files using the `reStructuredText
+<http://docutils.sourceforge.net/rst.html>`_ format. Please see the `SLEP —
+Template and Instructions
+<https://github.com/scikit-learn/enhancement_proposals/blob/master/slep_template.rst>`_
+file and the `reStructuredTextPrimer
+<https://www.sphinx-doc.org/en/stable/rest.html>`_ for more information. We use
+`Sphinx <https://www.sphinx-doc.org/en/stable/>`_ to convert SLEPs to HTML for
+viewing on the web.
+
+Header Preamble
+---------------
+
+Each SLEP must begin with a header preamble. The headers must appear in the
+following order. Headers marked with * are optional. All other headers are
+required::
+
+      :Author: <list of authors' real names and optionally, email addresses>
+      :Status: <Draft | Active | Accepted | Deferred | Rejected |
+               Withdrawn | Final | Superseded>
+      :Type: <Standards Track | Informational | Process>
+      :Created: <date created on, in yyyy-mm-dd format>
+    * :Requires: <slep numbers>
+    * :scikit-learn-Version: <version number>
+    * :Replaces: <slep number>
+    * :Replaced-By: <slep number>
+    * :Resolution: <url>
+
+The Author header lists the names, and optionally the email addresses of all
+the authors of the SLEP. The format of the Author header value must be
+
+    Random J. User <[email protected]>
+
+if the email address is included, and just
+
+    Random J. User
+
+if the address is not given. If there are multiple authors, each should be on a
+separate line.
+
+Copyright
+---------
+
+This document has been placed in the public domain [1]_.
+
+References and Footnotes
+------------------------
+
+.. [1] _Open Publication License: https://www.opencontent.org/openpub/