Skip to content

Commit cd87a5f

Browse files
effigieseffigies
authored
Merge pull request #1016 from matthew-brett/numfocus-application
WIP: Drafts of governance, roadmap
2 parents 9de0beb + e7d66fc commit cd87a5f

File tree

4 files changed

+262
-0
lines changed

4 files changed

+262
-0
lines changed

‎doc/source/devel/devguide.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,3 +108,16 @@ the algorithms with implications to the performance or validity of results.
108108

109109
It may list references to 3rd party bugtrackers, in case the reported bugs
110110
match the criteria listed above.
111+
112+
.. _mission_and_values:
113+
114+
.. _community_guidelines:
115+
116+
.. _code_of_conduct:
117+
118+
Community guidelines
119+
====================
120+
121+
Please see `our community guidelines
122+
<https://github.com/nipy/nibabel/blob/master/.github/CODE_OF_CONDUCT.md>`_.
123+
Other projects call these guidelines the "code of conduct".

‎doc/source/devel/governance.rst

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
.. _governance:
2+
3+
==============================
4+
Governance and Decision Making
5+
==============================
6+
7+
Abstract
8+
========
9+
10+
Nibabel is a consensus-based community project. Anyone with an interest in the
11+
project can join the community, contribute to the project design, and
12+
participate in the decision making process. This document describes how that
13+
participation takes place, how to find consensus, and how deadlocks are
14+
resolved.
15+
16+
Roles And Responsibilities
17+
==========================
18+
19+
The Community
20+
-------------
21+
22+
The Nibabel community consists of anyone using or working with the project
23+
in any way.
24+
25+
Contributors
26+
------------
27+
28+
Any community member can become a contributor by interacting directly with the
29+
project in concrete ways, such as:
30+
31+
- proposing a change to the code or documentation via a GitHub pull request;
32+
- reporting issues on our
33+
`GitHub issues page <https://github.com/nipy/nibabel/issues>`_;
34+
- discussing the design of the library, website, or tutorials on the
35+
`mailing list <https://mail.python.org/mailman/listinfo/neuroimaging>`_,
36+
or in existing issues and pull requests; or
37+
- reviewing
38+
`open pull requests <https://github.com/nipy/nibabel/pulls>`_,
39+
40+
among other possibilities. By contributing to the project, community members
41+
can directly help to shape its future.
42+
43+
Contributors should read the :ref:`contributor_guide` and our :ref:`code_of_conduct`.
44+
45+
Core Developers
46+
---------------
47+
48+
Core developers are community members that have demonstrated continued
49+
commitment to the project through ongoing contributions. They
50+
have shown they can be trusted to maintain Nibabel with care. Becoming a
51+
core developer allows contributors to merge approved pull requests, cast votes
52+
for and against merging a pull request, and be involved in deciding major
53+
changes to the API, and thereby more easily carry on with their project related
54+
activities. Core developers appear as team members on the `Nibabel Core Team
55+
page <https://github.com/orgs/nipy/teams/nibabel-core-developers/members>`_ and
56+
can be messaged ``@nipy/nibabel-core-developers``. We expect core developers to
57+
review code contributions while adhering to the :ref:`core_dev`.
58+
59+
New core developers can be nominated by any existing core developer. Discussion
60+
about new core developer nominations is one of the few activities that takes
61+
place on the project's private management list. The decision to invite a new
62+
core developer must be made by “lazy consensus”, meaning unanimous agreement by
63+
all responding existing core developers. Invitation must take place at least
64+
one week after initial nomination, to allow existing members time to voice any
65+
objections.
66+
67+
.. _steering_council:
68+
69+
Steering Council
70+
----------------
71+
The Steering Council (SC) members are core developers who have additional
72+
responsibilities to ensure the smooth running of the project. SC members are
73+
expected to participate in strategic planning, approve changes to the
74+
governance model, and make decisions about funding granted to the project
75+
itself. (Funding to community members is theirs to pursue and manage.) The
76+
purpose of the SC is to ensure smooth progress from the big-picture
77+
perspective. Changes that impact the full project require analysis informed by
78+
long experience with both the project and the larger ecosystem. When the core
79+
developer community (including the SC members) fails to reach such a consensus
80+
in a reasonable timeframe, the SC is the entity that resolves the issue.
81+
82+
Steering Council members appear as team members on the `Nibabel Steering
83+
Council Team page
84+
<https://github.com/orgs/nipy/teams/nibabel-steering-council/members>`_ and
85+
can be messaged ``@nipy/nibabel-steering-council``. Core
86+
87+
Decision Making Process
88+
=======================
89+
90+
Decisions about the future of the project are made through discussion with all
91+
members of the community. All non-sensitive project management discussion takes
92+
place on the project
93+
`mailing list <https://mail.python.org/mailman/listinfo/neuroimaging>`_
94+
and the `issue tracker <https://github.com/nipy/nibabel/issues>`_.
95+
Occasionally, sensitive discussion may occur on a private list.
96+
97+
Decisions should be made in accordance with our :ref:`mission_and_values`.
98+
99+
Nibabel uses a *consensus seeking* process for making decisions. The group
100+
tries to find a resolution that has no open objections among core developers.
101+
Core developers are expected to distinguish between fundamental objections to a
102+
proposal and minor perceived flaws that they can live with, and not hold up the
103+
decision making process for the latter. If no option can be found without
104+
an objection, the decision is escalated to the SC, which will itself use
105+
consensus seeking to come to a resolution. In the unlikely event that there is
106+
still a deadlock, the proposal will move forward if it has the support of a
107+
simple majority of the SC. Any proposal must be described by a Nibabel :ref:`biap`.
108+
109+
Decisions (in addition to adding core developers and SC membership as above)
110+
are made according to the following rules:
111+
112+
- **Minor documentation changes**, such as typo fixes, or addition / correction
113+
of a sentence (but no change of the Nibabel landing page or the “about”
114+
page), require approval by a core developer *and* no disagreement or
115+
requested changes by a core developer on the issue or pull request page (lazy
116+
consensus). We expect core developers to give “reasonable time” to others to
117+
give their opinion on the pull request if they’re not confident others would
118+
agree.
119+
120+
- **Code changes and major documentation changes** require agreement by *one*
121+
core developer *and* no disagreement or requested changes by a core developer
122+
on the issue or pull-request page (lazy consensus).
123+
124+
- **Changes to the API principles** require a :ref:`biap` and follow the
125+
decision-making process outlined above.
126+
127+
- **Changes to this governance model or our mission and values** require
128+
a :ref:`biap` and follow the decision-making process outlined above, *unless*
129+
there is unanimous agreement from core developers on the change.
130+
131+
If an objection is raised on a lazy consensus, the proposer can appeal to the
132+
community and core developers and the change can be approved or rejected by
133+
escalating to the SC, and if necessary, a BIAP (see below).
134+
135+
.. _biap:
136+
137+
Enhancement Proposals (BIAPs)
138+
=============================
139+
140+
Any proposals for enhancements of Nibabel should be written as a formal BIAP
141+
following the template :doc:`biap-template`. The BIAP must be made public and
142+
discussed before any vote is taken. The discussion must be summarized by a key
143+
advocate of the proposal in the appropriate section of the BIAP. Once this
144+
summary is made public and after sufficient time to allow the core team to
145+
understand it, they vote.
146+
147+
The workflow of a BIAP is detailed in :ref:`biap0`.
148+
149+
A list of all existing BIAPs is available :ref:`here <biap_list>`.
150+
151+
Acknowledgments
152+
===============
153+
154+
Many thanks to Jarrod Millman, Dan Schult and the Scikit-Image team for the
155+
`draft on which we based this document
156+
<https://networkx.github.io/documentation/latest/developer/nxeps/nxep-0001.html>`_.

‎doc/source/devel/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ Developer documentation page
1010
:maxdepth: 2
1111

1212
devguide
13+
governance
14+
roadmap
1315
add_test_data
1416
add_image_format
1517
devdiscuss

‎doc/source/devel/roadmap.rst

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
#######
2+
Roadmap
3+
#######
4+
5+
The roadmap is intended for larger, fundamental changes to the project that are
6+
likely to take months or years of developer time. Smaller-scoped items will
7+
continue to be tracked on our issue tracker.
8+
9+
The scope of these improvements means that these changes may be controversial,
10+
are likely to involve significant discussion among the core development team,
11+
and may require the creation of one or more NIAPs (Nibabel Increased
12+
Awesomeness Proposals).
13+
14+
==========
15+
Background
16+
==========
17+
18+
Nibabel is a workbench that provides a Python API for working with images in
19+
many formats. It is also a base library for tools implementing higher level
20+
processing.
21+
22+
Nibabel's success depends on:
23+
24+
* How easy it is to express common imaging tasks in the API.
25+
* The range of tasks it can perform.
26+
27+
An expressive, broad API will increase adoption and make it easier to teach.
28+
29+
Expressive API
30+
==============
31+
32+
Axis and tick labels
33+
--------------------
34+
35+
Brain images typically have three or four axes, whose meanings depend on the
36+
way the image was acquired. Axes have natural labels, expressing meaning, such
37+
as "time" or "slice", and they may have tick labels such as acquisition time.
38+
The scanner captures this information, but typical image formats cannot store
39+
it, so it is easy to lose metadata and make analysis errors; see
40+
`https://github.com/nipy/nibabel/wiki/BIAP6`_
41+
42+
We plan to expand Nibabel's API to encode axis and tick labels by integrating
43+
the Xarray package: `http://xarray.pydata.org`_. Xarray simplifies HDF5
44+
serialization, and visualization; see `https://napari.org`_.
45+
46+
An API for labels is not useful if we cannot read labels from the scanner
47+
data, or save them with the image. We plan to:
48+
49+
* Develop HDF5 equivalents of standard image formats, for serialization of
50+
data with labels.
51+
* Expand the current standard image format, NIfTI, to store labels in a JSON
52+
addition to image metadata: `https://github.com/nipy/nibabel/wiki/BIAP3`_.
53+
* Read image metadata from DICOM, the standard scanner format.
54+
55+
Reading and attaching DICOM data will start with code integrated from Dcmstack,
56+
by Brendan Moloney: `https://github.com/moloney/dcmstack`_; see:
57+
`https://github.com/nipy/nibabel/wiki/BIAP4`_.
58+
59+
DICOM metadata is often hidden inside "private" DICOM elements that need
60+
specialized parsers. We want to expand these parsers to preserve full metadata
61+
and build a normalization layer to abstract vendor-specific storage locations
62+
for metadata elements that describe the same thing.
63+
64+
API for surface data
65+
--------------------
66+
67+
Neuroimaging data often refers to locations on the brain surface. There are
68+
three common formats for such data: GIFTI, CIFTI and Freesurfer. Nibabel can
69+
read these formats, but lacks a standard API for reading and storing surface
70+
data with metadata; see `https://github.com/nipy/nibabel/issues/936`_,
71+
`https://github.com/nilearn/nilearn/issues/2171`_. We plan to develop
72+
a standard API, apply it to the standard formats, and design an efficient
73+
general HDF5 storage container for serializing surface data and metadata.
74+
75+
Range
76+
=====
77+
78+
Spatial transforms
79+
------------------
80+
81+
Neuroimaging toolboxes include spatial registration methods to align the
82+
objects and features present in two or more images. Registration methods
83+
estimate and store spatial transforms. There is no standard or compatible
84+
format to store and reuse these transforms, across packages.
85+
86+
Because Nibabel is a workbench, we want to extend its support to read
87+
transforms calculated with AFNI, FreeSurfer, FSL, ITK/ANTs, NiftyReg, and SPM.
88+
89+
We have developed the NiTransforms project for this task; we plan to complete
90+
and integrate NiTransforms into Nibabel. This will make transforms more
91+
accessible to researchers, and therefore easier to work with, and reason about.

0 commit comments

Comments
 (0)