# NiBabel

### Access a cacophony of neuro-imaging file formats

# BIAP 0 - Purpose and process

Author:

  Jarrod Millman <millman@berkeley.edu>

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 BIAP X — Template and Instructions 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:

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 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 BIAP X — Template and Instructions 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 <address@dom.ain>

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.

[2]

The URL for viewing BIAPs on the web is https://nipy.org/nibabel/devel/biaps/index.html