WIP: Drafts of governance, roadmap

doc/source/devel/devguide.rst

@@ -108,3 +108,16 @@ the algorithms with implications to the performance or validity of results.
 
 It may list references to 3rd party bugtrackers, in case the reported bugs
 match the criteria listed above.
+
+.. _mission_and_values:
+
+.. _community_guidelines:
+
+.. _code_of_conduct:
+
+Community guidelines
+====================
+
+Please see `our community guidelines
+<https://github.com/nipy/nibabel/blob/master/.github/CODE_OF_CONDUCT.md>`_.
+Other projects call these guidelines the "code of conduct".

doc/source/devel/governance.rst

@@ -0,0 +1,156 @@
+.. _governance:
+
+==============================
+Governance and Decision Making
+==============================
+
+Abstract
+========
+
+Nibabel is a consensus-based community project. Anyone with an interest in the
+project can join the community, contribute to the project design, and
+participate in the decision making process. This document describes how that
+participation takes place, how to find consensus, and how deadlocks are
+resolved.
+
+Roles And Responsibilities
+==========================
+
+The Community
+-------------
+
+The Nibabel community consists of anyone using or working with the project
+in any way.
+
+Contributors
+------------
+
+Any community member can become a contributor by interacting directly with the
+project in concrete ways, such as:
+
+- proposing a change to the code or documentation via a GitHub pull request;
+- reporting issues on our
+  `GitHub issues page <https://github.com/nipy/nibabel/issues>`_;
+- discussing the design of the library, website, or tutorials on the
+  `mailing list <https://mail.python.org/mailman/listinfo/neuroimaging>`_,
+  or in existing issues and pull requests; or
+- reviewing
+  `open pull requests <https://github.com/nipy/nibabel/pulls>`_,
+
+among other possibilities. By contributing to the project, community members
+can directly help to shape its future.
+
+Contributors should read the :ref:`contributor_guide` and our :ref:`code_of_conduct`.
+
+Core Developers
+---------------
+
+Core developers are community members that have demonstrated continued
+commitment to the project through ongoing contributions. They
+have shown they can be trusted to maintain Nibabel with care. Becoming a
+core developer allows contributors to merge approved pull requests, cast votes
+for and against merging a pull request, and be involved in deciding major
+changes to the API, and thereby more easily carry on with their project related
+activities. Core developers appear as team members on the `Nibabel Core Team
+page <https://github.com/orgs/nipy/teams/nibabel-core-developers/members>`_ and
+can be messaged ``@nipy/nibabel-core-developers``. We expect core developers to
+review code contributions while adhering to the :ref:`core_dev`.
+
+New core developers can be nominated by any existing core developer. Discussion
+about new core developer nominations is one of the few activities that takes
+place on the project's private management list. The decision to invite a new
+core developer must be made by “lazy consensus”, meaning unanimous agreement by
+all responding existing core developers. Invitation must take place at least
+one week after initial nomination, to allow existing members time to voice any
+objections.
+
+.. _steering_council:
+
+Steering Council
+----------------
+The Steering Council (SC) members are core developers who have additional
+responsibilities to ensure the smooth running of the project. SC members are
+expected to participate in strategic planning, approve changes to the
+governance model, and make decisions about funding granted to the project
+itself. (Funding to community members is theirs to pursue and manage.) The
+purpose of the SC is to ensure smooth progress from the big-picture
+perspective. Changes that impact the full project require analysis informed by
+long experience with both the project and the larger ecosystem. When the core
+developer community (including the SC members) fails to reach such a consensus
+in a reasonable timeframe, the SC is the entity that resolves the issue.
+
+Steering Council members appear as team members on the `Nibabel Steering
+Council Team page
+<https://github.com/orgs/nipy/teams/nibabel-steering-council/members>`_ and
+can be messaged ``@nipy/nibabel-steering-council``. Core
+
+Decision Making Process
+=======================
+
+Decisions about the future of the project are made through discussion with all
+members of the community. All non-sensitive project management discussion takes
+place on the project
+`mailing list <https://mail.python.org/mailman/listinfo/neuroimaging>`_
+and the `issue tracker <https://github.com/nipy/nibabel/issues>`_.
+Occasionally, sensitive discussion may occur on a private list.
+
+Decisions should be made in accordance with our :ref:`mission_and_values`.
+
+Nibabel uses a *consensus seeking* process for making decisions. The group
+tries to find a resolution that has no open objections among core developers.
+Core developers are expected to distinguish between fundamental objections to a
+proposal and minor perceived flaws that they can live with, and not hold up the
+decision making process for the latter.  If no option can be found without
+an objection, the decision is escalated to the SC, which will itself use
+consensus seeking to come to a resolution. In the unlikely event that there is
+still a deadlock, the proposal will move forward if it has the support of a
+simple majority of the SC. Any proposal must be described by a Nibabel :ref:`biap`.
+
+Decisions (in addition to adding core developers and SC membership as above)
+are made according to the following rules:
+
+- **Minor documentation changes**, such as typo fixes, or addition / correction
+  of a sentence (but no change of the Nibabel landing page or the “about”
+  page), require approval by a core developer *and* no disagreement or
+  requested changes by a core developer on the issue or pull request page (lazy
+  consensus). We expect core developers to give “reasonable time” to others to
+  give their opinion on the pull request if they’re not confident others would
+  agree.
+
+- **Code changes and major documentation changes** require agreement by *one*
+  core developer *and* no disagreement or requested changes by a core developer
+  on the issue or pull-request page (lazy consensus).
+
+- **Changes to the API principles** require a :ref:`biap` and follow the
+  decision-making process outlined above.
+
+- **Changes to this governance model or our mission and values** require
+  a :ref:`biap` and follow the decision-making process outlined above, *unless*
+  there is unanimous agreement from core developers on the change.
+
+If an objection is raised on a lazy consensus, the proposer can appeal to the
+community and core developers and the change can be approved or rejected by
+escalating to the SC, and if necessary, a BIAP (see below).
+
+.. _biap:
+
+Enhancement Proposals (BIAPs)
+=============================
+
+Any proposals for enhancements of Nibabel should be written as a formal BIAP
+following the template :doc:`biap-template`. The BIAP must be made public and
+discussed before any vote is taken. The discussion must be summarized by a key
+advocate of the proposal in the appropriate section of the BIAP. Once this
+summary is made public and after sufficient time to allow the core team to
+understand it, they vote.
+
+The workflow of a BIAP is detailed in :ref:`biap0`.
+
+A list of all existing BIAPs is available :ref:`here <biap_list>`.
+
+Acknowledgments
+===============
+
+Many thanks to Jarrod Millman, Dan Schult and the Scikit-Image team for the
+`draft on which we based this document
+<https://networkx.github.io/documentation/latest/developer/nxeps/nxep-0001.html>`_.

doc/source/devel/index.rst

@@ -10,6 +10,8 @@ Developer documentation page
     :maxdepth: 2
 
     devguide
+    governance
+    roadmap
     add_test_data
     add_image_format
     devdiscuss

doc/source/devel/roadmap.rst

@@ -0,0 +1,91 @@
+#######
+Roadmap
+#######
+
+The roadmap is intended for larger, fundamental changes to the project that are
+likely to take months or years of developer time. Smaller-scoped items will
+continue to be tracked on our issue tracker.
+
+The scope of these improvements means that these changes may be controversial,
+are likely to involve significant discussion among the core development team,
+and may require the creation of one or more NIAPs (Nibabel Increased
+Awesomeness Proposals).
+
+==========
+Background
+==========
+
+Nibabel is a workbench that provides a Python API for working with images in
+many formats.  It is also a base library for tools implementing higher level
+processing.
+
+Nibabel's success depends on:
+
+* How easy it is to express common imaging tasks in the API.
+* The range of tasks it can perform.
+
+An expressive, broad API will increase adoption and make it easier to teach.
+
+Expressive API
+==============
+
+Axis and tick labels
+--------------------
+
+Brain images typically have three or four axes, whose meanings depend on the
+way the image was acquired.  Axes have natural labels, expressing meaning, such
+as "time" or "slice", and they may have tick labels such as acquisition time.
+The scanner captures this information, but typical image formats cannot store
+it, so it is easy to lose metadata and make analysis errors; see
+`https://github.com/nipy/nibabel/wiki/BIAP6`_
+
+We plan to expand Nibabel's API to encode axis and tick labels by integrating
+the Xarray package: `http://xarray.pydata.org`_.  Xarray simplifies HDF5
+serialization, and visualization; see `https://napari.org`_.
+
+An API for labels is not useful if we cannot read labels from the scanner
+data, or save them with the image.  We plan to:
+
+* Develop HDF5 equivalents of standard image formats, for serialization of
+  data with labels.
+* Expand the current standard image format, NIfTI, to store labels in a JSON
+  addition to image metadata: `https://github.com/nipy/nibabel/wiki/BIAP3`_.
+* Read image metadata from DICOM, the standard scanner format.
+
+Reading and attaching DICOM data will start with code integrated from Dcmstack,
+by Brendan Moloney: `https://github.com/moloney/dcmstack`_; see:
+`https://github.com/nipy/nibabel/wiki/BIAP4`_.
+
+DICOM metadata is often hidden inside "private" DICOM elements that need
+specialized parsers. We want to expand these parsers to preserve full metadata
+and build a normalization layer to abstract vendor-specific storage locations
+for metadata elements that describe the same thing.
+
+API for surface data
+--------------------
+
+Neuroimaging data often refers to locations on the brain surface.  There are
+three common formats for such data: GIFTI, CIFTI and Freesurfer.  Nibabel can
+read these formats, but lacks a standard API for reading and storing surface
+data with metadata; see `https://github.com/nipy/nibabel/issues/936`_,
+`https://github.com/nilearn/nilearn/issues/2171`_.  We plan to develop
+a standard API, apply it to the standard formats, and design an efficient
+general HDF5 storage container for serializing surface data and metadata.
+
+Range
+=====
+
+Spatial transforms
+------------------
+
+Neuroimaging toolboxes include spatial registration methods to align the
+objects and features present in two or more images. Registration methods
+estimate and store spatial transforms.  There is no standard or compatible
+format to store and reuse these transforms, across packages.
+
+Because Nibabel is a workbench, we want to extend its support to read
+transforms calculated with AFNI, FreeSurfer, FSL, ITK/ANTs, NiftyReg, and SPM.
+
+We have developed the NiTransforms project for this task; we plan to complete
+and integrate NiTransforms into Nibabel.  This will make transforms more
+accessible to researchers, and therefore easier to work with, and reason about.