Skip to content

Commit 9f153cf

Browse files
oestebanoesteban
authored
Merge pull request #1 from nipreps/fmriprep-1963
ENH: Base documentation for the Community of NiPreps
2 parents b5f5216 + c2d80d4 commit 9f153cf

File tree

6 files changed

+277
-29
lines changed

6 files changed

+277
-29
lines changed

‎docs/community/CODE_OF_CONDUCT.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# *NiPreps* Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, sex characteristics, gender identity and expression,
9+
level of experience, education, socio-economic status, nationality, personal
10+
appearance, race, religion, or sexual identity and orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
* Using welcoming and inclusive language
18+
* Being respectful of differing viewpoints and experiences
19+
* Gracefully accepting constructive criticism
20+
* Focusing on what is best for the community
21+
* Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
* The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
* Trolling, insulting/derogatory comments, and personal or political attacks
28+
* Public or private harassment
29+
* Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or
41+
reject comments, commits, code, wiki edits, issues, and other contributions
42+
that are not aligned to this Code of Conduct, or to ban temporarily or
43+
permanently any contributor for other behaviors that they deem inappropriate,
44+
threatening, offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting Oscar Esteban at <[email protected]>
59+
or Chris Markiewicz at <[email protected]>, two members of the project team.
60+
All complaints will be reviewed and investigated and will result in a response that
61+
is deemed necessary and appropriate to the circumstances. The project team is
62+
obligated to maintain confidentiality with regard to the reporter of an incident.
63+
Further details of specific enforcement policies may be posted separately.
64+
65+
Project maintainers who do not follow or enforce the Code of Conduct in good
66+
faith may face temporary or permanent repercussions as determined by other
67+
members of the project's leadership.
68+
69+
## Attribution
70+
71+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
72+
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
73+
74+
[homepage]: https://www.contributor-covenant.org
75+
76+
For answers to common questions about this code of conduct, see
77+
https://www.contributor-covenant.org/faq

‎docs/devs/guidelines.md renamed to ‎docs/community/CONTRIBUTING.md

Lines changed: 3 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
# Contributing Guidelines
12

23
Welcome to the *NiPreps* project!
34
We're excited you're here and want to contribute.
@@ -299,37 +300,11 @@ These special positions can be revised to add names by punctual request and revi
299300
removal and update of ordering in an scheduled manner every two years.
300301
All the authors enlisted as *creators* participate in the revision of modifications.
301302

302-
### Developers
303-
304-
Developers are members of a wonderful team _driving the project_.
305-
Names and contacts of all developers are included in the
306-
[``.maint/developers.json`` file](https://github.com/poldracklab/fmriprep/blob/master/.maint/developers.json)
307-
Examples of steering activities that _drive the project_ are: actively participating in the
308-
follow-up meetings, leading documentation sprints, helping in the design of the tool and definition of the roadmap,
309-
providing resources (in the broad sense, including funding), code-review, etc.
310-
311-
### Contributors
312-
313-
Contributors enlisted in the
314-
[``.maint/contributors.json`` file](https://github.com/poldracklab/fmriprep/blob/master/.maint/contributors.json)
315-
actively help or have previously helped the project in a broad sense: writing code, writing documentation,
316-
benchmarking modules of the tool, proposing new features, helping improve the scientific
317-
rigor of implementations, giving out support on the different communication
318-
channels ([mattermost][link_mattermost], [NeuroStars][link_neurostars], [GitHub issues][link_issues], etc.).
319-
If you are new to the project, don't forget to add your name and affiliation to the list
320-
of contributors there!
321-
Our Welcome Bot will send an automated message reminding this to first-time contributors.
322-
Before every release, unlisted contributors will be invited again to add their names to the file
323-
(just in case they missed the automated message from our Welcome Bot).
324-
325-
Contributors who have contributed at some point to the project but were required or they wished to
326-
disconnect from the project's updates and to drop-out from publications and other dissemination activities,
327-
are listed in the [``.maint/former.json`` file](https://github.com/poldracklab/fmriprep/blob/master/.maint/former.json).
328-
329303
### Publications
330304

331305
Anyone listed as a *developer* or a *contributor* can start the submission process of a manuscript
332-
as first author.
306+
as first author (please see [Membership](members.md), where these concepts are
307+
described).
333308
To compose the author list, all the *creators* MUST be included (except for those people who
334309
opt to drop-out) and all the *contributors* MUST be invited to participate.
335310
First authorship(s) is (are) reserved for the authors that originated and kept the initiative

‎docs/community/features.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
2+
> The one bit that worries me is that *fMRIPrep* may become a Swiss army knife. I think instead it should just be a paring knife (small, efficient, and works for many things).
3+
>
4+
> -- <cite>Satra ([source](https://github.com/poldracklab/fmriprep/issues/1963#issuecomment-584455061))</cite>
5+
6+
When projects grow large, many forking paths created by newly implemented features start
7+
to open up.
8+
To account for this, the *NiPreps* community was created with the vision of building
9+
tools like *fMRIPrep* and *MRIQC* covering new imaging modalities, while keeping
10+
existing *NiPreps* tightly within scope.
11+
Defining such a scope also aids the implementation of the ease-of-use principle:
12+
13+
> The same way the scanner does not offer an immense space of knobs to turn
14+
> in the acquisition, *NiPreps* should not add many additional knobs to those
15+
> for them to be considered a viable *augmentation* or extension of the scanner hw/sw.
16+
>
17+
> -- <cite>Oscar ([source](https://github.com/poldracklab/fmriprep/issues/1963#issuecomment-584455061))</cite>
18+
19+
## The problem of feature creep
20+
To avert [feature creep](https://en.wikipedia.org/wiki/Feature_creep) and
21+
to serve each individual *NiPrep*, we developed the following
22+
guidelines, with the hopes of keeping these tools in a healthy state.
23+
24+
> I'm worried *fMRIPrep* is catching a case of featuritis
25+
>
26+
> -- <cite>Mathias ([source](https://github.com/poldracklab/fmriprep/issues/1985#issuecomment-588493059))</cite>
27+
28+
These guidelines should also serve the community to transparently drive the process
29+
of including proposals into the road-map, set the ground for healthy conversation,
30+
and establish some patterns when accepting new-feature contributions.
31+
Before proposing new features, please be mindful that a road-map may not exist
32+
for a particular *NiPrep*.
33+
Even when a development road-map exists, please understand that it is not always
34+
possible to rigorously follow them:
35+
36+
> I think something like this is what we tried to start sketching out with
37+
> the development roadmap. The concern, as I remember it, was that we couldn't
38+
> guarantee (or rule out) specific features when working with a small
39+
> development team.
40+
>
41+
> -- <cite>Elizabeth ([source](https://github.com/poldracklab/fmriprep/issues/1963#issuecomment-582453941))</cite>.
42+
43+
## Proposing a new feature
44+
45+
### Why the new feature is requested?
46+
Before going ahead and proposing a new feature, please take some time to
47+
learn whether the topic has been covered in the past and what decisions
48+
were made and why.
49+
This should be reasonably easy to do with the search tool of GitHub on the
50+
particular *NiPrep* repository.
51+
52+
If no previous discussion about the new idea is found,
53+
the next step is ensuring the new feature aligns with the vision and
54+
the scope of the target tool, as
55+
[Elizabeth points out](https://github.com/poldracklab/fmriprep/issues/1963#issuecomment-582453941).
56+
Taking a look into the Development Road-map of the particular project
57+
(if it exists), may help finding an answer.
58+
59+
If the new feature still seems pertinent after this preliminary work
60+
or you are unsure about whether it falls within the scope, then
61+
go ahead and post an issue requesting feedback on your proposal.
62+
Please make sure to clearly state why the new feature should be considered.
63+
64+
### Some questions will always be asked about a new feature
65+
[These questions by James](https://github.com/poldracklab/fmriprep/issues/1963#issuecomment-582220173)
66+
will certainly help build up the discourse in support of the new feature,
67+
as the *NiPreps* maintainers will consider them:
68+
69+
* **Is the user interface affected?**
70+
Because *NiPreps* generally expose a *command-line interface (CLI)* for the
71+
interaction with the user, new features involving changes to the CLI must be
72+
considered with caution as they may harm the ease-of-use:
73+
74+
> It also seems that some new features add more confusion than others.
75+
> Especially when the CLI is affected, and yet another option is added,
76+
> that makes the tool more complex to use.
77+
>
78+
> -- <cite>Alejandro ([source](https://github.com/poldracklab/fmriprep/ issues/1963#issuecomment-582174814))</cite>.
79+
80+
* Does the new feature substantially **increase the internal complexity**?
81+
Maintainers and developers will attempt to consolidate tools and lower the internal
82+
complexity whenever possible.
83+
This effort usually competes with the addition of new features as they typically will
84+
address particular use-cases rather than general improvements.
85+
However, that doesn't need to be the case, as some sections of the code might be
86+
objectively improvable and the integration of a new feature revising those might
87+
also lower complexity.
88+
Lowering the internal complexity will always be considered a great incentive
89+
for a new feature to be accepted.
90+
91+
* Is there **a standard procedure** for the proposed feature in the literature?
92+
93+
* if so, could we just use that procedure/value?
94+
95+
* Is the **feature dependent** on some attribute of the input data? (e.g., TR, duration, etc.)
96+
97+
* if so, can the procedure/value be determined algorithmically?
98+
99+
* Does the feature **interact with other settings**?
100+
For instance, [fmriprep#1962](https://github.com/poldracklab/fmriprep/pull/1962)
101+
interacts with the a/tCompCor implementation.
102+
103+
* What is the **difficulty of implementing the procedure outside** of a *NiPrep*?
104+
In other words, does the *NiPrep* provide all the necessary outputs for a
105+
user to perform the non-standard analysis?
106+
107+
108+
109+
### How the integration of the new feature will/can be validated?
110+
111+
Please propose ways to validate the new feature in the context of
112+
the workflow. Meaning, the objective here is to validate that the new
113+
feature works well within the pipeline, rather than validating a specific
114+
algorithm.
115+
To ensure the sustainability of *NiPreps*, the onus of this validation
116+
should be on the person/group requesting the feature.

‎docs/community/index.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Join the *NiPreps* Community
2+
3+
One of the pillars of *fMRIPrep*, the seed project for *NiPreps*,
4+
has been nurturing an open-source community.
5+
[Building Welcoming Communities](https://opensource.guide/building-community/)
6+
is crucial for open-source software because of several reasons:
7+
8+
* Engaging users and *contributors* (in a very liberal sense, not just with code)
9+
helps establish a development road-map:
10+
11+
* In the case of *fMRIPrep*, many users have reported bugs via our issue
12+
tracker and [Neurostars.org].
13+
Even though testing is one of the primary focuses for *fMRIPrep*, without these
14+
bug-report contributions the tool would have never reached the dependability level
15+
it requires to serve its purpose.
16+
* Users identify and propose new features, often illuminating shady areas the
17+
most involved developers did not find time or the right context to explore.
18+
19+
* The community exposes the software and also increases the externality of the software.
20+
The neuroimaging discussion supported by [Neurostars.org]
21+
has been a key factor for the adoption of *fMRIPrep*.
22+
23+
* Users always give back, and it is not uncommon to see elaborate responses
24+
to bug-reports and questions about *fMRIPrep* on [Neurostars.org]
25+
by users who had similar questions previously.
26+
27+
Because of the scientific purpose of *NiPreps*, there is one more **fundamental**
28+
reason to grow a (scientific) community around the tools: **rigor/scrutiny**.
29+
As one reviews a few of the most discussed pull-requests to *fMRIPrep*, very soon
30+
they realize that we don't just need to get the code right.
31+
We strive for integrating high-quality code, but even more importantly, that code
32+
must get the scientific method it implements right.
33+
This is particularly difficult because in most of the cases there aren't
34+
test oracles (in software engineering terms) or gold-standards (in scientific terms)
35+
to efficiently evaluate the validity of new features (even to exercise a minuscule area
36+
of the domain of inputs).
37+
The redundancy of expert eyes looking at our code has only helped make it better.
38+
39+
[Neurostars.org]: https://neurostars.org
40+

‎docs/community/members.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
In general, *NiPreps* embrace a [*liberal contribution model*](https://opensource.guide/leadership-and-governance/#what-are-some-of-the-common-governance-structures-for-open-source-projects)
2+
of governance structure.
3+
However, because of the scientific domain of *NiPreps*, the community features some
4+
structure from *meritocracy models* to prescribe the order in the
5+
authors list of [new papers about these tools](CONTRIBUTING.md#publications).
6+
7+
## Developers
8+
9+
Developers are members of a wonderful team _driving the project_.
10+
Names and contacts of all developers are included in the
11+
[`.maint/developers.json` file](https://github.com/poldracklab/fmriprep/blob/master/.maint/developers.json) of each project.
12+
Examples of steering activities that _drive the project_ are: actively participating in the
13+
follow-up meetings, leading documentation sprints, helping in the design of the tool and definition of the roadmap,
14+
providing resources (in the broad sense, including funding), code-review, etc.
15+
16+
## Contributors
17+
18+
Contributors enlisted in the
19+
[`.maint/contributors.json` file](https://github.com/poldracklab/fmriprep/blob/master/.maint/contributors.json) of each project
20+
actively help or have previously helped the project in a broad sense: writing code, writing documentation,
21+
benchmarking modules of the tool, proposing new features, helping improve the scientific
22+
rigor of implementations, giving out support on the different communication
23+
channels (mattermost, [NeuroStars][link_neurostars], GitHub, etc.).
24+
If you are new to the project, don't forget to add your name and affiliation to the list
25+
of contributors there!
26+
Our Welcome Bot will send an automated message reminding this to first-time contributors.
27+
Before every release, unlisted contributors will be invited again to add their names to the file
28+
(just in case they missed the automated message from our Welcome Bot).
29+
30+
Contributors who have contributed at some point to the project but were required or they wished to
31+
disconnect from the project's updates and to drop-out from publications and other dissemination activities,
32+
are listed in the [`.maint/former.json` file](https://github.com/poldracklab/fmriprep/blob/master/.maint/former.json).
33+
34+
35+
[link_neurostars]: https://neurostars.org

‎mkdocs.yml

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,13 @@ nav:
1818
- Introduction: apps/framework.md
1919
- Executing with Docker: apps/docker.md
2020
- Executing with Singularity: apps/singularity.md
21+
- Community:
22+
- Welcome: community/index.md
23+
- Membership: community/members.md
24+
- New features: community/features.md
25+
- Contributing: community/CONTRIBUTING.md
26+
- Code of Conduct: community/CODE_OF_CONDUCT.md
2127
- Developers:
22-
- Contributing Guidelines: devs/guidelines.md
2328
- Versions Matrix: devs/versions.md
2429
- Releases: devs/releases.md
2530
theme:

0 commit comments

Comments
 (0)