Merge pull request #1017 from matthew-brett/numfocus-application

MRG: add BIAP from Wiki

Author: effigies

doc/source/_static/biap_flowchart.png

@@ -0,0 +1,281 @@
+.. _biap0:
+
+============================
+BIAP 0 — Purpose and Process
+============================
+
+:Author: Jarrod Millman <[email protected]>
+:Status: Draft
+:Type: Process
+:Created: 2020-06-25
+
+
+What is a BIAP?
+---------------
+
+
+BIAP stands for Nibabel Enhancement Proposal.  BIAPs are 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
+Nibabel.  A BIAP should provide a concise technical specification of the
+feature and a rationale for the feature.  The BIAP author is responsible for
+building consensus within the community and documenting dissenting opinions.
+
+Because the BIAPs are maintained as text files in a versioned
+repository, their revision history is the historical record of the
+feature proposal [1]_.
+
+
+Types
+^^^^^
+
+There are three kinds of BIAPs:
+
+1. A **Standards Track** BIAP describes a new feature or implementation
+   for Nibabel.
+
+2. An **Informational** BIAP describes a Nibabel design issue, or provides
+   general guidelines or information to the Python community, but does not
+   propose a new feature. Informational BIAPs do not necessarily represent a
+   Nibabel community consensus or recommendation, so users and implementers are
+   free to ignore Informational BIAPs or follow their advice.
+
+3. A **Process** BIAP describes a process surrounding Nibabel, or
+   proposes a change to (or an event in) a process.  Process BIAPs are
+   like Standards Track BIAPs but apply to areas other than the Nibabel
+   language itself.  They may propose an implementation, but not to
+   Nibabel'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 Nibabel development.
+   Any meta-BIAP is also considered a Process BIAP.
+
+
+BIAP Workflow
+-------------
+
+The BIAP process begins with a new idea for Nibabel.  It is highly
+recommended that a single BIAP contain a single key proposal or new
+idea. Small enhancements or patches often don't need
+a BIAP and can be injected into the Nibabel development workflow with a
+pull request to the Nibabel `repo`_. The more focused the
+BIAP, the more successful it tends to be.
+If in doubt, split your BIAP into several well-focused ones.
+
+Each BIAP must have a champion---someone who writes the BIAP using the style
+and format described below, shepherds the discussions in the appropriate
+forums, and attempts to build community consensus around the idea.  The BIAP
+champion (a.k.a. Author) should first attempt to ascertain whether the idea is
+suitable for a BIAP. Posting to the Nibabel discussion `mailing list`_ is the
+best way to go about doing this.
+
+The proposal should be submitted as a draft BIAP via a `GitHub pull request`_
+to the ``doc/source/devel/biaps`` directory with the name ``biap_<n>.rst``
+where ``<n>`` is an appropriately assigned four-digit number (e.g.,
+``biap_0000.rst``). The draft must use the :doc:`biap_template` file.
+
+Once the PR for the BIAP 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 Author to update or expand the BIAP, or by maintainers to set
+its status, discussion URL, etc.
+
+Standards Track BIAPs 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 BIAP, 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 Nibabel repo (making sure to appropriately
+mark the PR as a WIP).
+
+
+Review and Resolution
+^^^^^^^^^^^^^^^^^^^^^
+
+BIAPs are discussed on the mailing list.  The possible paths of the
+status of BIAPs are as follows:
+
+.. image:: _static/biap_flowchart.png
+
+All BIAPs should be created with the ``Draft`` status.
+
+Eventually, after discussion, there may be a consensus that the BIAP
+should be accepted – see the next section for details. At this point
+the status becomes ``Accepted``.
+
+Once a BIAP 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 BIAP 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 BIAPs, provisionally accepted BIAPs may still be Rejected or Withdrawn
+even after the related changes have been included in a Python 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 BIAPs), as this status can lead to version
+compatibility challenges in the wider Nibabel ecosystem.
+
+A BIAP can also be assigned status ``Deferred``.  The BIAP author or a
+core developer can assign the BIAP this status when no progress is being made
+on the BIAP.
+
+A BIAP 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 BIAP author
+themselves has decided that the BIAP is actually a bad idea, or has
+accepted that a competing proposal is a better alternative.
+
+When a BIAP is ``Accepted``, ``Rejected``, or ``Withdrawn``, the BIAP 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.
+
+BIAPs can also be ``Superseded`` by a different BIAP, rendering the
+original obsolete.  The ``Replaced-By`` and ``Replaces`` headers
+should be added to the original and new BIAPs respectively.
+
+Process BIAPs may also have a status of ``Active`` if they are never
+meant to be completed, e.g. BIAP 0 (this BIAP).
+
+
+How a BIAP becomes Accepted
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A BIAP is ``Accepted`` by consensus of all interested contributors. We
+need a concrete way to tell whether consensus has been reached. When
+you think a BIAP is ready to accept, send an email to the
+Nibabel discussion mailing list with a subject like:
+
+  Proposal to accept BIAP #<number>: <title>
+
+In the body of your email, you should:
+
+* link to the latest version of the BIAP,
+
+* briefly describe any major points of contention and how they were
+  resolved,
+
+* include a sentence like: "If there are no substantive objections
+  within 7 days from this email, then the BIAP will be accepted; see
+  BIAP 0 for more details."
+
+After you send the email, you should make sure to link to the email
+thread from the ``Discussion`` section of the BIAP, so that people can
+find it later.
+
+Generally the BIAP 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 BIAP is on the verge of acceptance, and give them a final
+chance to respond. If there's some special reason to extend this final
+comment period beyond 7 days, then that's fine, just say so in the
+email. You shouldn't do less than 7 days, because sometimes people are
+travelling or similar and need some time 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 period passes without any substantive objections,
+then the BIAP can officially be marked ``Accepted``. You should send a
+followup email notifying the list (celebratory emoji optional but
+encouraged 🎉✨), and then update the BIAP by setting its ``:Status:``
+to ``Accepted``, and its ``:Resolution:`` header to a link to your
+followup email.
+
+If there *are* substantive objections, then the BIAP 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, disagreements about the direction or approach may
+require escalation to the Nibabel :ref:`steering_council` who
+then decide whether a controversial BIAP is ``Accepted``.
+
+
+Maintenance
+^^^^^^^^^^^
+
+In general, Standards track BIAPs 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 BIAPs may be updated as needed.
+
+Process BIAPs 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 BIAP being updated.
+
+
+Format and Template
+-------------------
+
+BIAPs are UTF-8 encoded text files using the reStructuredText_ format.  Please
+see the :doc:`biap_template` file and the reStructuredTextPrimer_ for more
+information.  We use Sphinx_ to convert BIAPs to HTML for viewing on the web
+[2]_.
+
+
+Header Preamble
+^^^^^^^^^^^^^^^
+
+Each BIAP 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 | Process>
+    :Created: <date created on, in dd-mmm-yyyy format>
+  * :Requires: <BIAP numbers>
+  * :Nibabel-Version: <version number>
+  * :Replaces: <BIAP number>
+  * :Replaced-By: <BIAP number>
+  * :Resolution: <url>
+
+The Author header lists the names, and optionally the email addresses
+of all the authors of the BIAP.  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.
+
+
+References and Footnotes
+------------------------
+
+.. [1] This historical record is available by the normal git commands
+   for retrieving older revisions, and can also be browsed on
+   `GitHub <https://github.com/nipy/nibabel/tree/master/doc/source/devel/biaps>`_.
+
+.. [2] The URL for viewing BIAPs on the web is
+   https://nipy.org/nibabel/devel/biaps/index.html
+
+.. _repo: https://github.com/nipy/nibabel
+
+.. _mailing list: https://mail.python.org/mailman/listinfo/neuroimaging
+
+.. _issue tracker: https://github.com/nipy/nibabel/issues
+
+.. _`GitHub pull request`: https://github.com/nipy/nibabel/pulls
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+.. _reStructuredTextPrimer: http://www.sphinx-doc.org/en/stable/rest.html
+
+.. _Sphinx: http://www.sphinx-doc.org/en/stable/