From 45e5ad7ab23f89dad091c3f0b6c7cc61062a0acc Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 8 Dec 2020 09:49:00 -0500 Subject: [PATCH] [DOC] Governance update (#615) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Added GovernanceSteeringDraft * Cleaning up governance text * cleaning up hyperlinks * Added project scope * typo fix Co-authored-by: Joshua Teves * typo fix Co-authored-by: Joshua Teves * Update docs/governance.rst typo fix Co-authored-by: Joshua Teves * Update docs/governance.rst opening sentence Co-authored-by: Elizabeth DuPre * Update docs/governance.rst typo correction Co-authored-by: Elizabeth DuPre * Update docs/governance.rst contributors can review PR Co-authored-by: Elizabeth DuPre * Update docs/governance.rst community review PR2 Co-authored-by: Elizabeth DuPre * Signif restructure based on PR feedback * Update docs/governance.rst typo fix Co-authored-by: Taylor Salo * Update docs/governance.rst rewording Co-authored-by: Joshua Teves * Update docs/governance.rst rewording Co-authored-by: Joshua Teves * Update docs/governance.rst typo Co-authored-by: Joshua Teves * Update docs/governance.rst typo Co-authored-by: Joshua Teves * Update docs/governance.rst typo Co-authored-by: Joshua Teves * Update docs/governance.rst rewording Co-authored-by: Joshua Teves * Update docs/governance.rst rewording * Update docs/governance.rst typo Co-authored-by: Joshua Teves * Update docs/governance.rst typo Co-authored-by: Joshua Teves * Update docs/governance.rst typo Co-authored-by: Joshua Teves * Update docs/governance.rst typo Co-authored-by: Joshua Teves * Update docs/governance.rst rewording Co-authored-by: Joshua Teves * Update docs/governance.rst typo Co-authored-by: Joshua Teves * fixing typos in governance.rst Co-authored-by: Joshua Teves * Rewording edits in contributing.rst and governance.rst Co-authored-by: Elizabeth DuPre * Apply suggestions from code review Changed votes from maintainers to contributors and changed voting timelines. Several other style changes or typo fixes. * Update docs/governance.rst added tentative steering committee * Apply suggestions from code review Several language changes for clarity & added Javier as a Maintainer. Co-authored-by: Eneko Uruñuela <13706448+eurunuela@users.noreply.github.com> * Adds steering committee link * Fix accidental heading * Fixes missing CoC link * Add @smoia as a CoC enforcer * Shortened line length and fixed typos * Fixes rst mistakes from myself * Fixes missing colons * Removes trailing whitespace * Fixes periods and whitespace in roadmap.rst * Text cleaning. Removed Kirstie as a maintainer * Apply suggestions from code review typo fixes Co-authored-by: Joshua Teves * Apply suggestions from code review typo/working fixes suggested by stalo Co-authored-by: Taylor Salo * Update docs/contributing.rst grammer fix * Apply suggestions from code review Language clarifications from emdupre's review Co-authored-by: Elizabeth DuPre * Fix warnings in html make Co-authored-by: Joshua Teves Co-authored-by: Elizabeth DuPre Co-authored-by: Taylor Salo Co-authored-by: Eneko Uruñuela <13706448+eurunuela@users.noreply.github.com> Co-authored-by: Joshua Teves --- docs/contributing.rst | 149 +++++++++++++++------ docs/governance.rst | 302 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + docs/roadmap.rst | 17 ++- docs/support.rst | 2 +- 5 files changed, 427 insertions(+), 44 deletions(-) create mode 100644 docs/governance.rst diff --git a/docs/contributing.rst b/docs/contributing.rst index 77b6abbd8..6a9436456 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -8,46 +8,121 @@ For a more practical guide to the tedana development, please see our .. _contributing guide: https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md -.. _governance: - -Governance ----------- - -Governance is a hugely important part of any project. -It is especially important to have clear process and communication channels -for open source projects that rely on a distributed network of volunteers, such as ``tedana``. - -``tedana`` is currently supported by a small group of five core developers. -Even with only five members involved in decision making processes, -we've found that setting expectations and communicating a shared vision has great value. - -By starting the governance structure early in our development, -we hope to welcome more people into the contributing team. -We are committed to continuing to update the governance structures as necessary. -Every member of the ``tedana`` community is encouraged to comment on these processes and suggest improvements. - -As the first interim `Benevolent Dictator for Life (BDFL)`_, -Elizabeth DuPre is ultimately responsible for any major decisions pertaining to ``tedana`` development. -However, all potential changes are explicitly and openly discussed in the described channels of -communication, and we strive for consensus amongst all community members. - -.. _Benevolent Dictator for Life (BDFL): https://en.wikipedia.org/wiki/Benevolent_dictator_for_life - Code of conduct ``````````````` -All ``tedana`` community members are expected to follow our `code of conduct`_ -during any interaction with the project. +All ``tedana`` community members are expected to follow our code of conduct +during any interaction with the project. `The full code of conduct is here`_. That includes---but is not limited to---online conversations, in-person workshops or development sprints, and when giving talks about the software. As stated in the code, severe or repeated violations by community members may result in exclusion from collective decision-making and rejection of future contributions to the ``tedana`` project. -.. _code of conduct: https://github.com/ME-ICA/tedana/blob/master/CODE_OF_CONDUCT.md +.. _The full code of conduct is here: https://github.com/ME-ICA/tedana/blob/master/CODE_OF_CONDUCT.md + +Scope of tedana +``````````````` +tedana is a collection of tools, software and a community related to echo time +(TE) dependent analyses. The umbrella of tedana covers a number of overlapping, +but somewhat distinct, ideas related to multi-echo analysis. This scope includes +collecting multi-echo data (Acquisition), combining those echoes together +(Combination), with optional noise removal (Denoising), inspecting the outputs +(Visualization) and answering multi-echo related questions (Community). In +general, tedana accepts previously preprocessed data to produce outputs that +are ready for further analyses. + +Acquisition +----------- + +While the development of multi-echo sequences is beyond the current scope +of tedana, the tedana community is committed to providing guidelines on current +multi-echo implementations. This will include both specific instructions for +how to collect multi-echo data for multiple vendors as well as details about +what types of data have been collected thus far. These details are subject to +change, and are intended to provide users with an idea of what is possible, +rather than definitive recommendations. + +Our focus is on functional MRI, including both magnitude and phase data, +however we understand that quantitative mapping has the potential to aid in +data processing. Thus, we believe that some details on non-functional MRI +acquisitions, such as detailed T2* mapping, may fall within the scope of +tedana. +Acquisition related details can be found in the `tedana Documentation.`_ + +.. _tedana Documentation.: https://tedana.readthedocs.io/en/latest/acquisition.html + +Combining echoes +---------------- + +An early step in processing data collected with multiple echoes is the +combination of the data into a single time series. We currently implement +multiple options to combine multi-echo data and will add more as they continue +to be developed. This is an area of active development and interest. + +Denoising +--------- + +tedana was developed out of a package known as `multi-echo ICA, ME-ICA, or MEICA`_ +developed by Dr. Prantik Kundu. Though the usage of ICA for classification of +signal vs noise components has continued in tedana, this is not a rule. The +tedana community is open and encouraging of new denoising methods, whether or not they +have a basis in ICA. + +Specifically, we are interested in any method that seeks to use the information from multiple +echoes to identify signal (defined here as BOLD signals arising from neural +processing) and noise (defined here as changes unrelated to neural +processing, such as motion, cardiac, respiration). + +tedana is primarily intended to work on volume data, that is, data that is +still in structured voxel space. This is because several of the currently used denoising metrics rely on spatial continuity, and they have not yet been updated to consider continuity over cortical vertices. +Therefore, surface-based denoising is not currently +within the scope of tedana, but code could be written so that it is a +possible option in the future. + +Currently tedana works on a single subject, run by run basis; however, methods +that use information across multiple runs are welcome. + +.. _`multi-echo ICA, ME-ICA, or MEICA`: https://github.com/ME-ICA/me-ica + +Visualization +------------- + +As part of the processing stream, tedana provides figures and an +HTML-based report for inspecting results. These are intended to help +users understand the outputs from tedana and diagnose problems. Though a +comprehensive viewer (such as fsleyes) is outside of the scope of tedana, we +will continue to improve the reports and add new information as needed. + +Community +--------- + +tedana is intended to be a community of multi-echo users. The primary resource +is the github repository and related documentation. In addition, the tedana +group will attempt to answer multi-echo related questions on NeuroStars +(`multi-echo tag `_ or +`tedana tag `_). + +What tedana isn’t +----------------- + +While the list of things that do not fall under the scope of tedana are +infinite, it is worth mentioning a few points: + +- tedana will not offer a GUI for usage +- it is intended to be either a stand + alone processing package or serve as a processing step as part of a larger + package (i.e. fmriprep or afni_proc.py). +- tedana will not provide basic preprocessing steps, such as motion correction + or slice timing correction. While these were previously part of the ME-ICA + pipeline, the sheer variety of possible choices, guidelines and data types + precludes including it within the tedana package. +- tedana will not provide statistical analyses in the form of general linear models, + connectivity or decoding. Though multi-echo data is amenable to all methods + of analysis, these methods will not be included in the tedana package. tedana's development philosophy --------------------------------------- +``````````````````````````````` In contributing to any open source project, we have found that it is hugely valuable to understand the core maintainers' development philosophy. @@ -65,7 +140,7 @@ These are: .. _exposing options to the user: Which options are available to users? -````````````````````````````````````` +------------------------------------- The ``tedana`` developers are committed to providing useful and interpretable outputs for a majority of use cases. @@ -104,7 +179,7 @@ listed on the ``tedana`` :ref:`support_ref` page. .. _prioritizing project developments: Structuring project developments -```````````````````````````````` +-------------------------------- The ``tedana`` developers have chosen to structure ongoing development around specific goals. When implemented successfully, this focuses the direction of the project and helps new contributors @@ -129,7 +204,7 @@ This allows us to: .. _backwards compatibility with meica: Is ``tedana`` backwards compatible with MEICA? -`````````````````````````````````````````````` +---------------------------------------------- The short answer is No. @@ -158,7 +233,7 @@ If you'd like to use MEICA as has been previously published the code is availabl .. _future-proofing for continuous development: How does ``tedana`` future-proof its development? -````````````````````````````````````````````````` +------------------------------------------------- ``tedana`` is a reasonably young project that is run by volunteers. No one involved in the development is paid for their time. @@ -179,7 +254,7 @@ applicable in the future as other needs arise. .. _when to release new software versions: When to release a new version -````````````````````````````` +----------------------------- In the broadest sense, we have adopted a "you know it when you see it" approach to releasing new versions of the software. @@ -203,13 +278,13 @@ Any member of the ``tedana`` community can propose that a new version is releas They should do so by opening an issue recommending a new release and giving a 1-2 sentence explanation of why the changes are sufficient to update the version. More information about what is required for a release to proceed is available -in the :ref:`release checklist`. +in the :ref:`release-checklist`. -.. _release checklist: +.. _release-checklist: Release Checklist -""""""""""""""""" +----------------- This is the checklist of items that must be completed when cutting a new release of tedana. These steps can only be completed by a project maintainer, but they are a good resource for diff --git a/docs/governance.rst b/docs/governance.rst new file mode 100644 index 000000000..d4e3aabd8 --- /dev/null +++ b/docs/governance.rst @@ -0,0 +1,302 @@ +Governance +========== +Governance is a hugely important part of any project. +It is especially important to have clear processes and communication channels +for open source projects that rely on a distributed network of volunteers, +such as ``tedana``. + +Overview +-------- + +Tedana is a relatively small open source project that requires specialized +knowledge in multiple domains. +This leads to several challenges. +No one +person on the current tedana development team has a combination of +available time plus expertise in collaborative software development, MRI +physics, and advanced data processing methods to assume a primary project +leader role. +Even if such a person was interested, it may not benefit the +project to overly rely on the existence of one person. +Instead, we developed the +following system with several goals in mind: + +- Grow the community. +- Strive for consensus. +- Provide a path for when consensus cannot be achieved. +- Minimize the administrative burden. +- Maximize the `bus factor`_ of the project. +- Acknowledge the leadership and time multiple people contribute to our + community without demanding more time than any individual can offer. + Dividing leadership responsibilities into multiple smaller roles also + makes it easier to encourage new people to take on a leadership role + without fearing that too much work will be required of them. +- Openness as a priority: + + - Promote open discussions. + - Openness is critical to building trust with the broader community + - Openness provides a mechanism for non-leaders to identify and address + oversights or mistakes + - Openness provides a smoother transition to onboard future leaders + - Leadership meetings should be open and notes should be shared unless + there are discussions about sensitive personal matters. + +This governance structure is a work-in-progress. +We welcome both people +who want to take on a leadership role as well as ideas to improve +this structure. + +Leadership +---------- + +Contributor + A contributor is someone who has made a contribution to tedana. + A contribution can be code, documentation, or conceptual. + All contributors are listed in the `all-contributors file`_. + The community decides on the content of this file using the same process + as any other change to the `Repository`_ (see below) allowing the + meaning of "Contributor" to evolve independently of the Decision-making + rules. + Contributors also have the option to be added to the Zenodo file which + may be used for authorship credit for tedana. + + +Maintainer + A Maintainer is responsible for the long term health of the project and + the community. + Maintainers have additional authority (see `Decision Making Process`_) + helping them to resolve conflicts and increase the pace of the + development when necessary. + Any maintainer can remove themselves. + Any contributor can become a maintainer by request, or by nomination of + a current maintainer, and with the support of the majority of the + current maintainers. + + Current Maintainers: + + +-------------------------------------------+ + | `Logan Dowdle`_ (@dowdlelt) | + +-------------------------------------------+ + | `Elizabeth DuPre`_ (@emdupre) | + +-------------------------------------------+ + | `Javier Gonzalez-Castillo`_ (@javiergcas) | + +-------------------------------------------+ + | `Dan Handwerker`_ (@handwerkerd) | + +-------------------------------------------+ + | `Taylor Salo`_ (@tsalo) | + +-------------------------------------------+ + | `Joshua Teves`_ (@jbteves) | + +-------------------------------------------+ + | `Eneko Uruñuela`_ (@eurunuela) | + +-------------------------------------------+ + +Steering committee + The :ref:`Steering Committee` is made up of a subset of maintainers who + help guide the project. + + Current Steering Committee members: + + +--------------------------------------+ + | `Logan Dowdle`_ (@dowdlelt) | + +--------------------------------------+ + | `Elizabeth DuPre`_ (@emdupre) | + +--------------------------------------+ + | `Dan Handwerker`_ (@handwerkerd) | + +--------------------------------------+ + | `Taylor Salo`_ (@tsalo) | + +--------------------------------------+ + | `Joshua Teves`_ (@jbteves) | + +--------------------------------------+ + | `Eneko Uruñuela`_ (@eurunuela) | + +--------------------------------------+ + +Focused Leadership Roles + We have identified key responsibilities or skills that help advance + tedana development and created roles for each of these responsibilities. + One person can fill more than one role and more than one person can + decide to share or split the responsibilities of a role. + Any contributor can propose the creation of new focused leadership roles. + A person can take on a leadership role without being a Maintainer or + Steering Committee member + + - | Task manager & record keeper: `Dan Handwerker`_ + + | Helps write & keep track of notes from meetings + | Keeps track of issues or items that should be addressed + | Follows up with people who volunteered to address an item or + alerts the broader community of known tasks that could use a + volunteer + - | MR physics leader: `César Caballero-Gaudes`_ + + | Someone who can make sure calculations fit within our + understanding of MR physics + | Someone who can either answer MRI physics questions related to + multi-echo or direct people to where they can find answers + - | Processing algorithms leaders: `Eneko Uruñuela`_ (Decomposition) & `Dan Handwerker`_ (Metrics & Decision Tree) + + | Someone who can make sure algorithms are appropriately implemented + (or knows enough to delegate to someone who can make sure + implementation is good) + | Someone who can either answer processing algorithm questions or + direct people to where they can find answers + - | Collaborative programming leaders: `Elizabeth DuPre`_ & `Joshua Teves`_ + | Helps make sure tedana is following best practices for Python code + design, testing, and communication for issues/pull requests etc. + - | Communications leader: `Joshua Teves`_ + | Mailing list manager & other outward-facing communication about + the project + - | New contributors leader: `Taylor Salo`_ + | Leads efforts to make contributor documentation more welcoming + | Is a point of contact for potential contributors to make them feel + welcome and direct them to relevant resources or issues + - | Multi-echo fMRI support leader: `Logan Dowdle`_ + | Monitors places where people may ask questions about tedana or + multi-echo fMRI and tries to find someone to answer those questions + - | Enforcer(s) of the `code of conduct`_: `Elizabeth DuPre`_ & `Dan Handwerker`_ & `Stefano Moia`_ + | People someone can go to if they want to report a code of conduct + violation + +Changing leaders +```````````````` +Any leader can remove themselves for a role at any time and open up a call +for a new self-nomination. +Anyone can request to take on a leadership role at any time. +Once per year, there should be an explicit call to the larger contributor +community asking if anyone wants to self nominate for a leadership role. +If individuals cannot reach consensus on who steps back and who assumes +new roles, then a majority vote of contributors from the previous 3 years +will assign people to roles where there are conflicts. + +If there are concerns with a tedana leader, any enforcer of the code of +conduct can ask anyone to step down from a leadership role. +If a person refuses to step down, then an enforcer of the code of conduct +will consult with the other code of conduct enforcers. +If they reach a concensus that a person shouldn't have a tedana leadership +position, then they should be removed. +If a code of conduct enforcer has a conflict of interest, then the +remaining code of conduct enforcers will identify someone without a +conflict to include in deliberations. + +Decision Making Process +----------------------- + +The rules outlined below are inspired by the +`decision-making rules for the BIDS standard `_, +which in turn were inspired by the +`lazy consensus system used in the Apache Foundation `_, +and heavily depend on the +`GitHub Pull Request review system `_. + +1. Potential modifications to the Repository should first be proposed via + an Issue. +2. Every modification (including a correction of a typo, adding a new + Contributor, an extension or others) or proposal to release a new + version needs to be done via a Pull Request (PR) to the Repository. +3. Anyone can open an Issue or a PR (this action is not limited to + Contributors). +4. A PR is eligible to be merged if and only if these conditions are met: + + a) The PR features at least two + `Reviews that Approve `_ + the PR of which neither is the author of the PR. + The reviews should be made after the last commit in the PR + (equivalent to + `Stale review dismissal `_ + option on GitHub). + If a second review requests minor changes after + another reviewer approved the PR, the first review does not need + to re-review. + b) Does not feature any + `Reviews that Request changes `_. + That is, if someone asked for changes, the PR should not be merged + just because two other people approve it. + c) Is not a Draft PR. + That is, the PR author says it is ready for review. + d) Passes all automated tests. + e) Is not proposing a new release. + f) The steering committee has not added extra restrictions. + For example, if a PR is a non-trival change, the steering committee + can create a system to get feedback from more than just two reviewers + before merging. +5. After consultation with contributors, the steering committee can decide + to merge any PR - even if it's not eligible to merge according to Rule 4. +6. Anyone can Review a PR and request changes. + If a community member requests changes they need to provide an + explanation regarding what changes should be made and justification of + their importance. + Reviews requesting changes can also be used to request more time to + review a PR. +7. A reviewer who requested changes can dismiss their own review, if they + decide their requested changes are no longer necessary, or approve + changes that address the issue underlying their change request. +8. If the author of a PR and a reviewer who requests changes cannot find a + solution that would lead to: + + (1) The author closing the PR without merging + (2) The reviewer accepting requested changes or + (3) The reviewer dismissing their review, so that the PR can be approved and + merged, then the disagreement will be resolved with a vote. +9. Rules governing voting: + + a) A vote can be triggered by any Maintainer, but only after 5 working + days from the time a Review Requesting Changes is made. + A PR can only have one open vote at a time. + If disagreements over a PR results in more than one + vote, the Steering Committee has the authority to create a voting + process to help resolve disagreements in a more efficient and + respectful manner. + b) Only Contributors can vote and each Contributor gets one vote. + c) A vote ends after 15 working days or when all Contributors have + voted or abstained (whichever comes first). + d) A vote freezes the PR - no new commits or Reviews Requesting Changes + can be added to it while a vote is ongoing. + If a commit is accidentally made during that period it should be + reverted. + Comments are allowed. + e) The quorum for a vote is five votes. + f) The outcome of the vote is decided based on a simple majority. + +.. _Steering Committee: + +Steering Committee +``````````````````` +The steering committee steers. +The goal of the steering committee is to help guide the direction of the +project. +Decisions in the steering committee will focus on how to present project +issues to the broader community in a clear way rather than making project +decisions without community input. + + +The steering committee can decide: + +- An issue should be prioritized for wider communal discussion. +- A pull request requires more discussion or reviews than standard before + merging. +- How a breaking change (something that changes existing user function calls + or program outputs) will be presented to the developer and user base for + discussion, before decisions are made. +- Criteria for cutting a new version release and when those criteria are met. + +Steering committee decisions should strive for consensus. +If consensus cannot be reached, the members of the steering committee +should vote. +Voting will take place over 7 days or until every steering committee member +votes or abstains. +The outcome of a vote is based on a simple majority. + + +.. _César Caballero-Gaudes: https://github.com/CesarCaballeroGaudes +.. _Logan Dowdle: https://github.com/dowdlelt +.. _Elizabeth DuPre: https://github.com/emdupre +.. _Javier Gonzalez-Castillo: https://github.com/javiergcas +.. _Dan Handwerker: https://github.com/handwerkerd +.. _Stefano Moia: https://github.com/smoia +.. _Taylor Salo: https://tsalo.github.io +.. _Joshua Teves: https://github.com/jbteves +.. _Eneko Uruñuela: https://github.com/eurunuela +.. _Kirstie Whitaker: https://github.com/KirstieJane +.. _code of conduct: https://github.com/ME-ICA/tedana/blob/master/CODE_OF_CONDUCT.md +.. _all-contributors file: https://github.com/ME-ICA/tedana/blob/master/.all-contributorsrc +.. _bus factor: https://en.wikipedia.org/wiki/Bus_factor +.. _Repository: https://github.com/ME-ICA/tedana> diff --git a/docs/index.rst b/docs/index.rst index f0f612bf4..a8736e41a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -162,6 +162,7 @@ tedana is licensed under GNU Lesser General Public License version 2.1. support contributing developing + governance roadmap api diff --git a/docs/roadmap.rst b/docs/roadmap.rst index fc9bf87f1..e2a9aa4aa 100644 --- a/docs/roadmap.rst +++ b/docs/roadmap.rst @@ -4,12 +4,17 @@ The tedana roadmap Project vision -------------- -ME-EPI processing is not well integrated into major preprocessing packages, -yielding duplicated and unmaintained code. -``tedana`` has been developed to address this need and will serve as a central repository -for standard ME-EPI denoising as well as a testing ground for novel ME-EPI denoising methods. -This will jointly reduce the external burden on pipeline maintainers, -facilitate increased ME-EPI adoption, and enable future development in ME-EPI denoising. +``tedana`` was originally developed as a place for the multi-echo fMRI +denoising method that was originally defined in ME-ICA +(`ME-ICA source `_). +tedana was designed to be more understandable, modular, and adaptable so +that it can serve as a testing ground for novel multi-echo fMRI denoising +methods. +We have expanded to welcome additional multi-echo fMRI processing +approaches, and to support communal resources for multi-echo fMRI, whether +or not they directly involve the tedana software. + +A more detailed `project scope is here `_ Metrics of success and corresponding milestones ----------------------------------------------- diff --git a/docs/support.rst b/docs/support.rst index 470e0c154..dadbf3ac8 100644 --- a/docs/support.rst +++ b/docs/support.rst @@ -6,7 +6,7 @@ All bugs, concerns and enhancement requests for this software can be submitted h If you would like to ask a question about tedana-specific usage or tedana's outputs, please submit a question to `NeuroStars`_ with the `tedana tag`_. -If you would like to ask a general question about multi-echo fMRI, please submit it to `NeuroStars`_ with the `multi-echo tag`_. +If you would like to ask a general question about multi-echo fMRI, please submit it to `NeuroStars`_ with the `multi-echo tag`_. Note: All previous tedana-related questions are available under the `multi-echo tag`_.