From a84275dd6b4fd571389afae5a0546052ffd2fc23 Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Mon, 19 Oct 2020 23:00:00 -0400 Subject: [PATCH 01/46] Added GovernanceSteeringDraft --- docs/contributing.rst | 25 ----- docs/governance.rst | 252 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 3 files changed, 253 insertions(+), 25 deletions(-) create mode 100644 docs/governance.rst diff --git a/docs/contributing.rst b/docs/contributing.rst index 77b6abbd8..adda022b6 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -8,31 +8,6 @@ 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 ``````````````` diff --git a/docs/governance.rst b/docs/governance.rst new file mode 100644 index 000000000..c86d3443d --- /dev/null +++ b/docs/governance.rst @@ -0,0 +1,252 @@ +Governance +========== + + +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. We developed the +following system three goals in mind: + +1. Acknowledge the leadership and time multiple people contribute to our + community without demanding more time than any individual can offer. + Dividing leadership responsabilies 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. +2. Identify people who are willing to be the point-people who contribute + their expertise to specific areas of the project. +3. Create a governance structure that will provide a mechanism for making + decisions without relying on highly structured systems that may be + necessary for larger projects, but would weight a project of our size + down with unncessary complexity. + +This governance structure is a work-in-progress. We welcome both people +who want to take on a leadership role as well as ideas for our to improve +this structure. + +Steering Committee and Leadership Roles +--------------------------------------- + +Organizational Principles +````````````````````````` +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. + +Issues or pull requests that can be reviewed by any community member can be +reviewed and approved by the steering committee or steering committee members. +The steering committee can decide that an issue should be prioritized for wider +communal discussion or that a pull request requires more discussion or reviews +than standard before merging. The steering committee can also decide how a +breaking change (something that changes existing user function calls or outputs) +will be presented to the developer and user base for discussion and decision +making. + +Steering committee decisions should strive for consensus and accept the +majority’s decision. If voting is necessary, it can happen asynchronously and is +defined as more than half of the members of the steering committee. If a member +of the steering committee is unable to spend the time necessary to understand +an issue & vote, they can temporarily recuse from decisions so that the number of +committee members is reduced + +Openness is a priority: + +- Openness is critical to building trust with the broader community +- Openness provides a mechanism for non-steering committee members to identify + and address steering committee blindspots +- Openness provides a smoother transition to onboard future steering committee + members +- If steering committee discussions (written or verbal) could welcome any + community member without compromising efficiency, they should be. The + steering committee can schedule discussions without needing to ask about the + availability for people outside of the steering committee. If notes from + meetings can be openly shared without compromising personal privacy, they + should be. + +The current members are the tedana steering committee are. If you are interested +in joining the steering committee, please let the current members know: + +- Name 1 & link to github profile +- Name 2 & link to github profile +- Name 3 & link to github profile +- Name 4 & link to github profile +- Name 5 & link to github profile + +Leadership roles +```````````````` +We have identified key skills that help advance tedana development and +volunteers who will be the point-people for each of these roles. One person +can fill more than one role and more than one person can decide to share or +split the responsabilities of a role. The steering committee will include +people who also take on leadership roles, but a person can take on a leadership +role without also volunteering to be on the steering committee. + +If you are interested in taking over one of these roles, slitting a role, or +creating a new leadership role, please talk to some of the current leaders. + +- | 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 understand 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 leader `Eneko Uruñuela `_ (Decomposiiton) & `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 leader `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 tried to find someone to answer those questions +- | Enforcer(s) of the Code of Conduct `Elizabeth DuPre `_ & `Dan Handwerker `_ & another volunteer + | A person or people someone can go to if they want to report a code of conduct violation + | If this is one person, that person should NOT be on the steering committee + | If this is more than one person, at least one should not be on the steering committee + | Ideal is someone who cares about tedana but DOESN’T know contributors well enough to say, ”Person X would never do that” + +Changing leaders +```````````````` +Steering committee members can remove themselves from the steering committee 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 +membership on the steering committee or other leadership roles. 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 steering committee member or 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 can call +a vote of contributors to remove an individual from a leadership role in tedana. + + +.. _Decision_making + +Decision Making Process +----------------------- + +Introduction +```````````` + +The tedana community sets out the following decision-making rules with the intention to: + +- Strive for consensus. +- Promote open discussions. +- Minimize the administrative burden. +- Provide a path for when consensus cannot be achieved. +- Grow the community. +- Maximize the `bus factor `_ of the project. + +The rules outlined below are inspired by the +`decision-making rules for the BIDS standard `_, +and heavily depends on `GitHub Pull Request review system `_. + +Definitions +``````````` + +Repository + `https://github.com/ME-ICA/tedana `_ + +Contributor + Person 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. + +Maintainer + A Contributor responsible for the long term health of the project and the + community. Maintainers have additional rights (see Rules) helping them to + resolve conflicts and increase the pace of the development when necessary. + Any maintainer can self-remove themselves. Any contributor can become a + maintainer by request and with the support of the majority of the current + maintainers. Current Maintainers: + + +--------------------------------------------------------------------+-----------------+ + | Name | Time commitment | + +====================================================================+=================+ + | Logan Dowdle (`@dowdlelt `_) | 0.5h/week | + +--------------------------------------------------------------------+-----------------+ + | Elizabeth DuPre (`@emdupre `_) | 0.5h/week | + +--------------------------------------------------------------------+-----------------+ + | Dan Handwerker (`@handwerkerd `_) | 0.5h/week | + +--------------------------------------------------------------------+-----------------+ + | Ross Markello (`@rmarkello `_) | 0.5h/week | + +--------------------------------------------------------------------+-----------------+ + | Taylor Salo (`@tsalo `_) | 3h/week | + +--------------------------------------------------------------------+-----------------+ + | Joshua Teves (`@jbteves `_) | 0.5h/week | + +--------------------------------------------------------------------+-----------------+ + | Eneko Urunuela (`@eurunuela `_) | 0.5h/week | + +--------------------------------------------------------------------+-----------------+ + | Kirstie Whitaker (`@KirstieJane `_)| 0.5h/week | + +--------------------------------------------------------------------+-----------------+ + +Rules +````` + +1. Potential modifications to the Repository should first be proposed via an + Issue. Rules regarding Votes apply to both Pull Requests and Issues. + + - Every modification of the specification (including a correction of a + typo, adding a new Contributor, an extension adding support for a new + data type, or others) or proposal to release a new version needs to be + done via a Pull Request (PR) to the Repository. +2. Anyone can open a PR (this action is not limited to Contributors). +3. PRs adding new Contributors must also add their GitHub names to the + `all-contributors file `_. + This should be done with the allcontributors bot. + + - Contributors may also add themselves to the Zenodo file if they wish, + but this is not mandatory. +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 from Maintainers of which neither is the author of the PR. + The reviews need to be made after the last commit in the PR (equivalent to + `Stale review dismissal `_ + option on GitHub). + b) Does not feature any `Reviews that Request changes `_. + c) Does not feature "WIP" in the title (Work in Progress). + d) Passes all automated tests. + e) Is not proposing a new release or has been approved by at least one + Maintainer (i.e., PRs proposing new releases need to be approved by + at least one Maintainer). +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. Any Maintainer can Review a PR and request changes. If a Maintainer Requests + changes they need to provide an explanation regarding what changes should + be added and justification of their importance. Reviews requesting + changes can also be used to request more time to review a PR. +7. A Maintainer who Requested changes can Dismiss their own review or Approve + changes added by the Contributor who opened the PR. +8. If the author of a PR and Maintainer who provided Review that Requests + changes cannot find a solution that would lead to the Maintainer dismissing + their review or accepting the changes the Review can be Dismissed 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 has been raised and in case a + Vote has been triggered previously no sooner than 15 working days since + its conclusion. + b) Only Maintainers can vote and each Maintainer gets one vote. + c) A Vote ends after 7 working days or when all Maintainers have voted + (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. + e) The quorum for a Vote is five votes. + f) The outcome of the vote is decided based on a simple majority. diff --git a/docs/index.rst b/docs/index.rst index 0d52ea263..9f1bcb05b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -161,6 +161,7 @@ tedana is licensed under GNU Lesser General Public License version 2.1. support contributing developing + governance roadmap api From 705366014c17209d5e0e1440f517bc13c3edfd5c Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 20 Oct 2020 10:32:46 -0400 Subject: [PATCH 02/46] Cleaning up governance text --- docs/governance.rst | 84 +++++++++++++++++++-------------------------- 1 file changed, 35 insertions(+), 49 deletions(-) diff --git a/docs/governance.rst b/docs/governance.rst index c86d3443d..6a1ad83a4 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -12,19 +12,19 @@ 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. We developed the -following system three goals in mind: - -1. Acknowledge the leadership and time multiple people contribute to our - community without demanding more time than any individual can offer. - Dividing leadership responsabilies 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. -2. Identify people who are willing to be the point-people who contribute - their expertise to specific areas of the project. -3. Create a governance structure that will provide a mechanism for making - decisions without relying on highly structured systems that may be - necessary for larger projects, but would weight a project of our size - down with unncessary complexity. +following system the following goals in mind: + +- Promote open discussions. +- Minimize the administrative burden. +- Strive for consensus. +- Provide a path for when consensus cannot be achieved. +- Grow the community. +- 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 responsabilies 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. This governance structure is a work-in-progress. We welcome both people who want to take on a leadership role as well as ideas for our to improve @@ -45,16 +45,16 @@ reviewed and approved by the steering committee or steering committee members. The steering committee can decide that an issue should be prioritized for wider communal discussion or that a pull request requires more discussion or reviews than standard before merging. The steering committee can also decide how a -breaking change (something that changes existing user function calls or outputs) -will be presented to the developer and user base for discussion and decision -making. +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. Steering committee decisions should strive for consensus and accept the majority’s decision. If voting is necessary, it can happen asynchronously and is defined as more than half of the members of the steering committee. If a member of the steering committee is unable to spend the time necessary to understand -an issue & vote, they can temporarily recuse from decisions so that the number of -committee members is reduced +an issue & vote, they can recuse from a decision so that the number of committee +members is reduced Openness is a priority: @@ -63,15 +63,14 @@ Openness is a priority: and address steering committee blindspots - Openness provides a smoother transition to onboard future steering committee members -- If steering committee discussions (written or verbal) could welcome any - community member without compromising efficiency, they should be. The +- If steering committee discussions (written or verbal) could include + community members without compromising efficiency, should be invited. The steering committee can schedule discussions without needing to ask about the availability for people outside of the steering committee. If notes from meetings can be openly shared without compromising personal privacy, they should be. -The current members are the tedana steering committee are. If you are interested -in joining the steering committee, please let the current members know: +The current members of the tedana steering committee are: - Name 1 & link to github profile - Name 2 & link to github profile @@ -79,6 +78,8 @@ in joining the steering committee, please let the current members know: - Name 4 & link to github profile - Name 5 & link to github profile +If you are interested in joining the steering committee, please let the current members know. + Leadership roles ```````````````` We have identified key skills that help advance tedana development and @@ -88,16 +89,15 @@ split the responsabilities of a role. The steering committee will include people who also take on leadership roles, but a person can take on a leadership role without also volunteering to be on the steering committee. -If you are interested in taking over one of these roles, slitting a role, or +If you are interested in taking over one of these roles, splitting a role, or creating a new leadership role, please talk to some of the current leaders. - | 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 + | 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 understand of MR physics + | 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 leader `Eneko Uruñuela `_ (Decomposiiton) & `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) @@ -110,8 +110,8 @@ creating a new leadership role, please talk to some of the current leaders. | 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 tried to find someone to answer those questions -- | Enforcer(s) of the Code of Conduct `Elizabeth DuPre `_ & `Dan Handwerker `_ & another volunteer + | 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 `_ & another volunteer | A person or people someone can go to if they want to report a code of conduct violation | If this is one person, that person should NOT be on the steering committee | If this is more than one person, at least one should not be on the steering committee @@ -139,21 +139,11 @@ a vote of contributors to remove an individual from a leadership role in tedana. Decision Making Process ----------------------- -Introduction -```````````` - -The tedana community sets out the following decision-making rules with the intention to: - -- Strive for consensus. -- Promote open discussions. -- Minimize the administrative burden. -- Provide a path for when consensus cannot be achieved. -- Grow the community. -- Maximize the `bus factor `_ of the project. - -The rules outlined below are inspired by the -`decision-making rules for the BIDS standard `_, -and heavily depends on `GitHub Pull Request review system `_. +These 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 `_. Definitions ``````````` @@ -201,17 +191,13 @@ Rules 1. Potential modifications to the Repository should first be proposed via an Issue. Rules regarding Votes apply to both Pull Requests and Issues. - - Every modification of the specification (including a correction of a - typo, adding a new Contributor, an extension adding support for a new - data type, or others) or proposal to release a new version needs to be - done via a Pull Request (PR) to the Repository. + - Every modification of the specification (including a correction of a typo, adding a new Contributor, an extension adding support for a new data type, or others) or proposal to release a new version needs to be done via a Pull Request (PR) to the Repository. 2. Anyone can open a PR (this action is not limited to Contributors). 3. PRs adding new Contributors must also add their GitHub names to the `all-contributors file `_. This should be done with the allcontributors bot. - - Contributors may also add themselves to the Zenodo file if they wish, - but this is not mandatory. + - Contributors may also add themselves to the Zenodo file if they wish, but this is not mandatory. 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 `_ From 6a7d90fff9cccef6add9db5f1620b180327bdfa9 Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 20 Oct 2020 11:57:09 -0400 Subject: [PATCH 03/46] cleaning up hyperlinks --- docs/contributing.rst | 10 +++--- docs/governance.rst | 79 +++++++++++++++++++++++++------------------ 2 files changed, 51 insertions(+), 38 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index adda022b6..dbb7b6696 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -11,15 +11,15 @@ For a more practical guide to the tedana development, please see our 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 tedana's development philosophy -------------------------------------- @@ -181,10 +181,8 @@ More information about what is required for a release to proceed is available in the :ref:`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 index 6a1ad83a4..109bbdd2d 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -19,7 +19,7 @@ following system the following goals in mind: - Strive for consensus. - Provide a path for when consensus cannot be achieved. - Grow the community. -- Maximize the `bus factor `_ of the project. +- 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 responsabilies into multiple smaller roles also @@ -30,6 +30,8 @@ This governance structure is a work-in-progress. We welcome both people who want to take on a leadership role as well as ideas for our to improve this structure. + + Steering Committee and Leadership Roles --------------------------------------- @@ -92,31 +94,33 @@ role without also volunteering to be on the steering committee. If you are interested in taking over one of these roles, splitting a role, or creating a new leadership role, please talk to some of the current leaders. -- | Task manager & record keeper: `Dan Handwerker `_ +- | 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 `_ +- | 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 leader `Eneko Uruñuela `_ (Decomposiiton) & `Dan Handwerker `_ (Metrics & Decision Tree) +- | Processing algorithms leader `Eneko Uruñuela`_ (Decomposiiton) & `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 leader `Elizabeth DuPre `_ & `Joshua Teves `_ +- | Collaborative programming leader `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 `_ +- | Communications leader `Joshua Teves`_ | Mailing list manager & other outward-facing communication about the project -- | New contributors leader `Taylor Salo `_ +- | 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 `_ +- | 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 `_ & another volunteer +- | Enforcer(s) of the `code of conduct`_ `Elizabeth DuPre`_ & `Dan Handwerker`_ & another volunteer | A person or people someone can go to if they want to report a code of conduct violation | If this is one person, that person should NOT be on the steering committee | If this is more than one person, at least one should not be on the steering committee | Ideal is someone who cares about tedana but DOESN’T know contributors well enough to say, ”Person X would never do that” + + Changing leaders ```````````````` Steering committee members can remove themselves from the steering committee at @@ -134,8 +138,6 @@ If a person refuses to step down, then an enforcer of the code of conduct can ca a vote of contributors to remove an individual from a leadership role in tedana. -.. _Decision_making - Decision Making Process ----------------------- @@ -152,7 +154,7 @@ Repository `https://github.com/ME-ICA/tedana `_ Contributor - Person listed in the `all-contributors file `_. + Person 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. @@ -165,25 +167,26 @@ Maintainer maintainer by request and with the support of the majority of the current maintainers. Current Maintainers: - +--------------------------------------------------------------------+-----------------+ - | Name | Time commitment | - +====================================================================+=================+ - | Logan Dowdle (`@dowdlelt `_) | 0.5h/week | - +--------------------------------------------------------------------+-----------------+ - | Elizabeth DuPre (`@emdupre `_) | 0.5h/week | - +--------------------------------------------------------------------+-----------------+ - | Dan Handwerker (`@handwerkerd `_) | 0.5h/week | - +--------------------------------------------------------------------+-----------------+ - | Ross Markello (`@rmarkello `_) | 0.5h/week | - +--------------------------------------------------------------------+-----------------+ - | Taylor Salo (`@tsalo `_) | 3h/week | - +--------------------------------------------------------------------+-----------------+ - | Joshua Teves (`@jbteves `_) | 0.5h/week | - +--------------------------------------------------------------------+-----------------+ - | Eneko Urunuela (`@eurunuela `_) | 0.5h/week | - +--------------------------------------------------------------------+-----------------+ - | Kirstie Whitaker (`@KirstieJane `_)| 0.5h/week | - +--------------------------------------------------------------------+-----------------+ + +-----------------------------------+-----------------+ + | Name | Time commitment | + +===================================+=================+ + | `Logan Dowdle`_ (@dowdlelt) | 0.5h/week | + +-----------------------------------+-----------------+ + | `Elizabeth DuPre`_ (@emdupre) | 0.5h/week | + +-----------------------------------+-----------------+ + | `Dan Handwerker`_ (@handwerkerd) | 0.5h/week | + +-----------------------------------+-----------------+ + | `Ross Markello`_ (@rmarkello) | 0.5h/week | + +-----------------------------------+-----------------+ + | `Taylor Salo`_ (@tsalo) | 3h/week | + +-----------------------------------+-----------------+ + | `Joshua Teves`_ (@jbteves) | 0.5h/week | + +-----------------------------------+-----------------+ + | `Eneko Uruñuela`_ (@eurunuela) | 0.5h/week | + +-----------------------------------+-----------------+ + | `Kirstie Whitaker`_ (@KirstieJane)| 0.5h/week | + +-----------------------------------+-----------------+ + Rules ````` @@ -194,7 +197,7 @@ Rules - Every modification of the specification (including a correction of a typo, adding a new Contributor, an extension adding support for a new data type, or others) or proposal to release a new version needs to be done via a Pull Request (PR) to the Repository. 2. Anyone can open a PR (this action is not limited to Contributors). 3. PRs adding new Contributors must also add their GitHub names to the - `all-contributors file `_. + `all-contributors file`_. This should be done with the allcontributors bot. - Contributors may also add themselves to the Zenodo file if they wish, but this is not mandatory. @@ -236,3 +239,15 @@ Rules during that period it should be reverted. e) The quorum for a Vote is five votes. f) The outcome of the vote is decided 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 +.. _Dan Handwerker: https://github.com/handwerkerd +.. _Ross Markello: https://github.com/rmarkello +.. _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 +.. _all-contributors file: https://github.com/ME-ICA/tedana/blob/master/.all-contributorsrc +.. _bus factor: https://en.wikipedia.org/wiki/Bus_factor \ No newline at end of file From a076998b4f6acbfcdbe220f9fb3636bc937eb381 Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 20 Oct 2020 12:29:58 -0400 Subject: [PATCH 04/46] Added project scope --- docs/contributing.rst | 107 +++++++++++++++++++++++++++++++++++++++--- docs/roadmap.rst | 16 ++++--- 2 files changed, 110 insertions(+), 13 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index dbb7b6696..c328b75ba 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -21,8 +21,101 @@ from collective decision-making and rejection of future contributions to the ``t .. _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 covers +collecting multi-echo data (Acquisition), combining those echoes together +(Combining), with optional noise removal (Denoising), inspecting the outputs +(Visualization) and answering multi-echo related questions (Community). In +general, preprocessed data is pushed through tedana, producing outputs that +are ready for further analyses. + +Acquisition +----------- + +While the development of multi-echo sequences is far 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. + +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 methods, whether or not they +have a basis in ICA. + +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 spurious changes unrelated to neural +processing, i.e. motion, cardiac, respiration). + +tedana is primarily intended to work on volume data, that is, data that is +still in structured voxel space. Surface-based denoising is not currently +within the scope of tedana, but code should 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. + +Visualization +------------- + +Though tedana does not provide a GUI for inspecting results, it does produce +figures as part of the processing stream. These figures 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 figures and add new ones 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 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. @@ -40,7 +133,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. @@ -79,7 +172,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 @@ -104,7 +197,7 @@ This allows us to: .. _backwards compatibility with meica: Is ``tedana`` backwards compatible with MEICA? -`````````````````````````````````````````````` +---------------------------------------------- The short answer is No. @@ -133,7 +226,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. @@ -154,7 +247,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. @@ -182,7 +275,7 @@ in the :ref:`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/roadmap.rst b/docs/roadmap.rst index fc9bf87f1..43dc4d711 100644 --- a/docs/roadmap.rst +++ b/docs/roadmap.rst @@ -4,12 +4,16 @@ 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 people use the tedana +software. + +A more detailed `project scope is here `_ Metrics of success and corresponding milestones ----------------------------------------------- From 305a5d0931766eca75a95ba0fbeca08627b865e1 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 20 Oct 2020 13:24:47 -0400 Subject: [PATCH 05/46] typo fix Co-authored-by: Joshua Teves --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index c328b75ba..ada621be6 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -12,7 +12,7 @@ Code of conduct ``````````````` 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`_ +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. From 33d13c2f5360f4a3afba1bc1b71bae08410671fa Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 20 Oct 2020 13:25:52 -0400 Subject: [PATCH 06/46] typo fix Co-authored-by: Joshua Teves --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index ada621be6..bfc83093b 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -76,7 +76,7 @@ still in structured voxel space. Surface-based denoising is not currently within the scope of tedana, but code should 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 +Currently tedana works on a single subject, run by run basis; however, methods that use information across multiple runs are welcome. Visualization From f5ed9dbff9efc652b6563a906288d2da46963a42 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 20 Oct 2020 13:26:45 -0400 Subject: [PATCH 07/46] Update docs/governance.rst typo fix Co-authored-by: Joshua Teves --- docs/governance.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/governance.rst b/docs/governance.rst index 109bbdd2d..ced543c3c 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -66,7 +66,7 @@ Openness is a priority: - Openness provides a smoother transition to onboard future steering committee members - If steering committee discussions (written or verbal) could include - community members without compromising efficiency, should be invited. The + community members without compromising efficiency, they should be invited. The steering committee can schedule discussions without needing to ask about the availability for people outside of the steering committee. If notes from meetings can be openly shared without compromising personal privacy, they @@ -250,4 +250,4 @@ Rules .. _Eneko Uruñuela: https://github.com/eurunuela .. _Kirstie Whitaker: https://github.com/KirstieJane .. _all-contributors file: https://github.com/ME-ICA/tedana/blob/master/.all-contributorsrc -.. _bus factor: https://en.wikipedia.org/wiki/Bus_factor \ No newline at end of file +.. _bus factor: https://en.wikipedia.org/wiki/Bus_factor From 1843e2c1fd02b0cb56a514cacf9c0dce48e4d0dc Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 20 Oct 2020 21:24:17 -0400 Subject: [PATCH 08/46] Update docs/governance.rst opening sentence Co-authored-by: Elizabeth DuPre --- docs/governance.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index ced543c3c..e096b15d9 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -1,6 +1,8 @@ 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``. Overview -------- From 361b264b6fa534614966c4a38dcd6cdd8f4172e5 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 20 Oct 2020 21:32:51 -0400 Subject: [PATCH 09/46] Update docs/governance.rst typo correction Co-authored-by: Elizabeth DuPre --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index e096b15d9..446ea2b67 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -58,7 +58,7 @@ majority’s decision. If voting is necessary, it can happen asynchronously and defined as more than half of the members of the steering committee. If a member of the steering committee is unable to spend the time necessary to understand an issue & vote, they can recuse from a decision so that the number of committee -members is reduced +members is reduced. Openness is a priority: From bae82f9c36858ca3d2efa75fc13c247d530c7a34 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Wed, 21 Oct 2020 12:18:55 -0400 Subject: [PATCH 10/46] Update docs/governance.rst contributors can review PR Co-authored-by: Elizabeth DuPre --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index 446ea2b67..0e27cbc3a 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -218,7 +218,7 @@ Rules at least one Maintainer). 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. Any Maintainer can Review a PR and request changes. If a Maintainer Requests +6. Any community member can Review a PR and request changes. If a community member Requests changes they need to provide an explanation regarding what changes should be added and justification of their importance. Reviews requesting changes can also be used to request more time to review a PR. From a01f51614a5a4af00f10be28f03fdce5ee805d88 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Wed, 21 Oct 2020 12:19:23 -0400 Subject: [PATCH 11/46] Update docs/governance.rst community review PR2 Co-authored-by: Elizabeth DuPre --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index 0e27cbc3a..c8970c845 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -222,7 +222,7 @@ Rules changes they need to provide an explanation regarding what changes should be added and justification of their importance. Reviews requesting changes can also be used to request more time to review a PR. -7. A Maintainer who Requested changes can Dismiss their own review or Approve +7. A community member who Requested changes can Dismiss their own review or Approve changes added by the Contributor who opened the PR. 8. If the author of a PR and Maintainer who provided Review that Requests changes cannot find a solution that would lead to the Maintainer dismissing From 1bed00e4e67ebf542c367d55dbff1f13c1419820 Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Wed, 21 Oct 2020 21:49:41 -0400 Subject: [PATCH 12/46] Signif restructure based on PR feedback --- docs/governance.rst | 361 +++++++++++++++++++++----------------------- 1 file changed, 175 insertions(+), 186 deletions(-) diff --git a/docs/governance.rst b/docs/governance.rst index c8970c845..502975586 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -14,242 +14,231 @@ 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. We developed the -following system the following goals in mind: +following system the several goals in mind: -- Promote open discussions. -- Minimize the administrative burden. +- Grow the community. - Strive for consensus. - Provide a path for when consensus cannot be achieved. -- Grow the community. +- 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 responsabilies 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 is 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 + blindspots + - Openness provides a smoother transition to onboard future leaders + - Leadership meetings should be open and notes should be shared unless + there are discusssions about senisitive 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 for our 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. + -Steering Committee and Leadership Roles ---------------------------------------- - -Organizational Principles -````````````````````````` -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. - -Issues or pull requests that can be reviewed by any community member can be -reviewed and approved by the steering committee or steering committee members. -The steering committee can decide that an issue should be prioritized for wider -communal discussion or that a pull request requires more discussion or reviews -than standard before merging. The steering committee can also decide 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. - -Steering committee decisions should strive for consensus and accept the -majority’s decision. If voting is necessary, it can happen asynchronously and is -defined as more than half of the members of the steering committee. If a member -of the steering committee is unable to spend the time necessary to understand -an issue & vote, they can recuse from a decision so that the number of committee -members is reduced. - -Openness is a priority: - -- Openness is critical to building trust with the broader community -- Openness provides a mechanism for non-steering committee members to identify - and address steering committee blindspots -- Openness provides a smoother transition to onboard future steering committee - members -- If steering committee discussions (written or verbal) could include - community members without compromising efficiency, they should be invited. The - steering committee can schedule discussions without needing to ask about the - availability for people outside of the steering committee. If notes from - meetings can be openly shared without compromising personal privacy, they - should be. - -The current members of the tedana steering committee are: - -- Name 1 & link to github profile -- Name 2 & link to github profile -- Name 3 & link to github profile -- Name 4 & link to github profile -- Name 5 & link to github profile - -If you are interested in joining the steering committee, please let the current members know. - -Leadership roles -```````````````` -We have identified key skills that help advance tedana development and -volunteers who will be the point-people for each of these roles. One person -can fill more than one role and more than one person can decide to share or -split the responsabilities of a role. The steering committee will include -people who also take on leadership roles, but a person can take on a leadership -role without also volunteering to be on the steering committee. - -If you are interested in taking over one of these roles, splitting a role, or -creating a new leadership role, please talk to some of the current leaders. - -- | 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 leader `Eneko Uruñuela`_ (Decomposiiton) & `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 leader `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`_ & another volunteer - | A person or people someone can go to if they want to report a code of conduct violation - | If this is one person, that person should NOT be on the steering committee - | If this is more than one person, at least one should not be on the steering committee - | Ideal is someone who cares about tedana but DOESN’T know contributors well enough to say, ”Person X would never do that” - +Maintainer + A Contributor 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 self-remove themselves. Any contributor can become a + maintainer by request and with the support of the majority of the current + maintainers. Current Maintainers: + +-----------------------------------+ + | `Logan Dowdle`_ (@dowdlelt) | + +-----------------------------------+ + | `Elizabeth DuPre`_ (@emdupre) | + +-----------------------------------+ + | `Dan Handwerker`_ (@handwerkerd) | + +-----------------------------------+ + | `Taylor Salo`_ (@tsalo) | + +-----------------------------------+ + | `Joshua Teves`_ (@jbteves) | + +-----------------------------------+ + | `Eneko Uruñuela`_ (@eurunuela) | + +-----------------------------------+ + | `Kirstie Whitaker`_ (@KirstieJane)| + +-----------------------------------+ + +Steering committee + The steering committee is made up of a subset of maintainers who help guide + the project. Current Steering Committee members: + + +----------------------------------------------+ + | `Dan Handwerker`_ (@handwerkerd) (tentative) | + +----------------------------------------------+ + | Your name here! | + +----------------------------------------------+ + | Your name here! | + +----------------------------------------------+ + | Your name here! | + +----------------------------------------------+ + | Your name here! | + +----------------------------------------------+ + +Focused Leadership Roles + We have identified key responsabilities or skills that help advance tedana + development and created roles for each of these responsabilities. One + person can fill more than one role and more than one person can decide to + share or split the responsabilities of a role. Any contributor can proposed + 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 leader `Eneko Uruñuela`_ (Decomposiiton) & `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 leader `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`_ & another volunteer + | A person or people someone can go to if they want to report a code of conduct violation + | If this is one person, that person should NOT be on the steering committee + | If this is more than one person, at least one should not be on the steering committee + | Ideal is someone who cares about tedana but DOESN’T know contributors well enough to say, ”Person X would never do that” Changing leaders ```````````````` -Steering committee members can remove themselves from the steering committee 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 -membership on the steering committee or other leadership roles. 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 steering committee member or 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 can call -a vote of contributors to remove an individual from a leadership role in tedana. - +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 enforces. If they reach a concensus that a person shouldn't have a +tedana leadership position, then they should be removed. Of a code of conduct +enforcer as a conflict of interest, then the remaining code of conduct enforcers +will identify someone without a conflict to include in deliberations. Decision Making Process ----------------------- -These rules outlined below are inspired by the +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 `_. -Definitions -``````````` - -Repository - `https://github.com/ME-ICA/tedana `_ - -Contributor - Person 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. - -Maintainer - A Contributor responsible for the long term health of the project and the - community. Maintainers have additional rights (see Rules) helping them to - resolve conflicts and increase the pace of the development when necessary. - Any maintainer can self-remove themselves. Any contributor can become a - maintainer by request and with the support of the majority of the current - maintainers. Current Maintainers: - - +-----------------------------------+-----------------+ - | Name | Time commitment | - +===================================+=================+ - | `Logan Dowdle`_ (@dowdlelt) | 0.5h/week | - +-----------------------------------+-----------------+ - | `Elizabeth DuPre`_ (@emdupre) | 0.5h/week | - +-----------------------------------+-----------------+ - | `Dan Handwerker`_ (@handwerkerd) | 0.5h/week | - +-----------------------------------+-----------------+ - | `Ross Markello`_ (@rmarkello) | 0.5h/week | - +-----------------------------------+-----------------+ - | `Taylor Salo`_ (@tsalo) | 3h/week | - +-----------------------------------+-----------------+ - | `Joshua Teves`_ (@jbteves) | 0.5h/week | - +-----------------------------------+-----------------+ - | `Eneko Uruñuela`_ (@eurunuela) | 0.5h/week | - +-----------------------------------+-----------------+ - | `Kirstie Whitaker`_ (@KirstieJane)| 0.5h/week | - +-----------------------------------+-----------------+ - - -Rules -````` - -1. Potential modifications to the Repository should first be proposed via an - Issue. Rules regarding Votes apply to both Pull Requests and Issues. - - - Every modification of the specification (including a correction of a typo, adding a new Contributor, an extension adding support for a new data type, or others) or proposal to release a new version needs to be done via a Pull Request (PR) to the Repository. -2. Anyone can open a PR (this action is not limited to Contributors). -3. PRs adding new Contributors must also add their GitHub names to the - `all-contributors file`_. - This should be done with the allcontributors bot. - - - Contributors may also add themselves to the Zenodo file if they wish, but this is not mandatory. +1. Potential modifications to the Repository should first be proposed via an + Issue. +2. Every modification of the specification (including a correction of a typo, + adding a new Contributor, an extension adding support for a new data type, + 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 from Maintainers of which neither is the author of the PR. - The reviews need to be made after the last commit in the PR (equivalent to + 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). + 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 `_. - c) Does not feature "WIP" in the title (Work in Progress). + 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 or has been approved by at least one - Maintainer (i.e., PRs proposing new releases need to be approved by - at least one Maintainer). + 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. Any community member can Review a PR and request changes. If a community member Requests - changes they need to provide an explanation regarding what changes should - be added and justification of their importance. Reviews requesting - changes can also be used to request more time to review a PR. -7. A community member who Requested changes can Dismiss their own review or Approve - changes added by the Contributor who opened the PR. -8. If the author of a PR and Maintainer who provided Review that Requests - changes cannot find a solution that would lead to the Maintainer dismissing - their review or accepting the changes the Review can be Dismissed with a vote. +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 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 has been raised and in case a - Vote has been triggered previously no sooner than 15 working days since - its conclusion. + a) A vote can be triggered by any Maintainer, but only after 5 working days + from the time a Review Requesting Changes. If a PR has a disagreement + that required a vote, there must be at least 15 days from the conclusion + of the first vote before another vote can be triggered. b) Only Maintainers can vote and each Maintainer gets one vote. - c) A Vote ends after 7 working days or when all Maintainers have voted - (whichever comes first). - d) A Vote freezes the PR - no new commits or Reviews Requesting changes can + c) A vote ends after 7 working days or when all Maintainers 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. - e) The quorum for a Vote is five votes. + 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 +``````````````````` +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 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 .. _Dan Handwerker: https://github.com/handwerkerd -.. _Ross Markello: https://github.com/rmarkello .. _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 .. _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> \ No newline at end of file From 40b1bd3779ec4d47356a5f918af10531c66c46e2 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Wed, 21 Oct 2020 22:25:43 -0400 Subject: [PATCH 13/46] Update docs/governance.rst typo fix Co-authored-by: Taylor Salo --- docs/governance.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/governance.rst b/docs/governance.rst index 502975586..d15cf72ed 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -14,7 +14,7 @@ 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. We developed the -following system the several goals in mind: +following system with several goals in mind: - Grow the community. - Strive for consensus. @@ -241,4 +241,4 @@ The outcome of a vote is based on a simple majority. .. _Kirstie Whitaker: https://github.com/KirstieJane .. _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> \ No newline at end of file +.. _Repository: https://github.com/ME-ICA/tedana> From b983b229caa3c1086e506130c38c1e643a18e701 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 09:42:33 -0400 Subject: [PATCH 14/46] Update docs/governance.rst rewording Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index d15cf72ed..6a8d9c754 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -31,7 +31,7 @@ following system with several goals in mind: - Promote open discussions. - Openness is critical to building trust with the broader community - Openness provides a mechanism for non-leaders to identify and address - blindspots + 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 discusssions about senisitive personal matters. From bfc4cbe067795589e9609a29afb4cca4940275a5 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 09:43:16 -0400 Subject: [PATCH 15/46] Update docs/governance.rst rewording Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index 6a8d9c754..0ea39d36b 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -26,7 +26,7 @@ following system with several goals in mind: Dividing leadership responsabilies 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 is a priority: +- Openness as a priority: - Promote open discussions. - Openness is critical to building trust with the broader community From 84b06a114b80d613cb7e3b363562b36d59baf869 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 09:43:53 -0400 Subject: [PATCH 16/46] Update docs/governance.rst typo Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index 0ea39d36b..d6067c486 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -34,7 +34,7 @@ following system with several goals in mind: 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 discusssions about senisitive personal matters. + 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 for our to improve From d623cd687794a6b9912094a2a1ae7dccf15ac2bd Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 09:48:03 -0400 Subject: [PATCH 17/46] Update docs/governance.rst typo Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index d6067c486..15a635470 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -54,7 +54,7 @@ Contributor Maintainer - A Contributor responsible for the long term health of the project and the + A Contributor 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 self-remove themselves. Any contributor can become a From fe4303367f6420004ca10860d4bacea762b4f506 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 09:51:25 -0400 Subject: [PATCH 18/46] Update docs/governance.rst typo Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index 15a635470..53d9e03c5 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -57,7 +57,7 @@ Maintainer A Contributor 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 self-remove themselves. Any contributor can become a + Any maintainer can remove themselves. Any contributor can become a maintainer by request and with the support of the majority of the current maintainers. Current Maintainers: From a525512b637d76beb4fef5ba93517c69df9bd6f8 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 09:52:02 -0400 Subject: [PATCH 19/46] Update docs/governance.rst rewording Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index 53d9e03c5..e2623c9f5 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -156,7 +156,7 @@ and heavily depend on the 1. Potential modifications to the Repository should first be proposed via an Issue. -2. Every modification of the specification (including a correction of a typo, +2. Every modification (including a correction of a typo, adding a new Contributor, an extension adding support for a new data type, or others) or proposal to release a new version needs to be done via a Pull Request (PR) to the Repository. From 83742718ab72c6d838d6706ecd19088af51649bd Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 09:53:51 -0400 Subject: [PATCH 20/46] Update docs/governance.rst rewording --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index e2623c9f5..c077242ff 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -58,7 +58,7 @@ Maintainer 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 and with the support of the majority of the current + maintainer by request, or by nomination of a current maintainer, and with the support of the majority of the current maintainers. Current Maintainers: +-----------------------------------+ From 5082db5f7d1685d3951db4912acb939ca203054f Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 11:48:11 -0400 Subject: [PATCH 21/46] Update docs/governance.rst typo Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index c077242ff..51334f671 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -94,7 +94,7 @@ Steering committee +----------------------------------------------+ Focused Leadership Roles - We have identified key responsabilities or skills that help advance tedana + We have identified key responsibilities or skills that help advance tedana development and created roles for each of these responsabilities. One person can fill more than one role and more than one person can decide to share or split the responsabilities of a role. Any contributor can proposed From efd87774e070297d7555835c21cbfa5bddd82ae1 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 11:48:31 -0400 Subject: [PATCH 22/46] Update docs/governance.rst typo Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index 51334f671..e723b23e2 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -95,7 +95,7 @@ Steering committee Focused Leadership Roles We have identified key responsibilities or skills that help advance tedana - development and created roles for each of these responsabilities. One + 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 responsabilities of a role. Any contributor can proposed the creation of new focused leadership roles. A person can take on a From 4a178154f575220ca66ff1ef493654516a90e38d Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 11:48:56 -0400 Subject: [PATCH 23/46] Update docs/governance.rst typo Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index e723b23e2..f357d0b88 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -97,7 +97,7 @@ 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 responsabilities of a role. Any contributor can proposed + 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 From 3a74a8253c91131118a020472c96a564bc338c4c Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 11:49:58 -0400 Subject: [PATCH 24/46] Update docs/governance.rst typo Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index f357d0b88..ca68bd9e4 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -109,7 +109,7 @@ Focused Leadership Roles - | 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 leader `Eneko Uruñuela`_ (Decomposiiton) & `Dan Handwerker`_ (Metrics & Decision Tree) + - | Processing algorithms leader `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 leader `Elizabeth DuPre`_ & `Joshua Teves`_ From 8d4a591d6914af83d6225a7b6ffa10edfcfd82ee Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 11:50:48 -0400 Subject: [PATCH 25/46] Update docs/governance.rst rewording Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index ca68bd9e4..f6c749d05 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -157,7 +157,7 @@ and heavily depend on the 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 adding support for a new data type, + 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). From 01e4342ff6a4f4b166b598eb41f6830eea80f69d Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 11:51:07 -0400 Subject: [PATCH 26/46] Update docs/governance.rst typo Co-authored-by: Joshua Teves --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index f6c749d05..12f7c55bd 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -175,7 +175,7 @@ and heavily depend on the 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 + 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. From 706c91dd4183018075decce1edbed746b0342882 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Thu, 22 Oct 2020 11:55:52 -0400 Subject: [PATCH 27/46] fixing typos in governance.rst Co-authored-by: Joshua Teves --- docs/governance.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/governance.rst b/docs/governance.rst index 12f7c55bd..b3d2228ef 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -182,10 +182,10 @@ and heavily depend on the 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 + 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 +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 @@ -196,13 +196,13 @@ and heavily depend on the 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. If a PR has a disagreement + from the time a Review Requesting Changes is made. If a PR has a disagreement that required a vote, there must be at least 15 days from the conclusion of the first vote before another vote can be triggered. b) Only Maintainers can vote and each Maintainer gets one vote. c) A vote ends after 7 working days or when all Maintainers have voted or abstained (whichever comes first). - d) A vote freezes the PR - no new commits or Reviews Requesting changes can + 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. @@ -217,13 +217,13 @@ rather than making project decisions without community input. The steering committee can decide: -- An issue should be prioritized for wider communal discussion +- An issue should be prioritized for wider communal discussion. - A 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 +- 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 From 592230e839cb483b196ca687d01fc88bdc3d77f9 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Mon, 26 Oct 2020 11:37:35 -0400 Subject: [PATCH 28/46] Rewording edits in contributing.rst and governance.rst Co-authored-by: Elizabeth DuPre --- docs/contributing.rst | 14 +++++++------- docs/governance.rst | 6 +++--- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index bfc83093b..9172e0f1b 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -25,11 +25,11 @@ 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 covers +but somewhat distinct ideas related to multi-echo analysis. This scope includes collecting multi-echo data (Acquisition), combining those echoes together (Combining), with optional noise removal (Denoising), inspecting the outputs (Visualization) and answering multi-echo related questions (Community). In -general, preprocessed data is pushed through tedana, producing outputs that +general, tedana accepts previously preprocessed data to produce outputs that are ready for further analyses. Acquisition @@ -63,12 +63,12 @@ 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 methods, whether or not they +tedana community is open and encouraging of new denoising methods, whether or not they have a basis in ICA. -We are interested in any method that seeks to use the information from multiple +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 spurious changes unrelated to neural +processing) and noise (defined here as changes unrelated to neural processing, i.e. motion, cardiac, respiration). tedana is primarily intended to work on volume data, that is, data that is @@ -86,7 +86,7 @@ Though tedana does not provide a GUI for inspecting results, it does produce figures as part of the processing stream. These figures 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 figures and add new ones as needed. +will continue to improve the reports and add new information as needed. Community --------- @@ -110,7 +110,7 @@ infinite, it is worth mentioning a few points: 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 analyses in the form of general linear models, +- 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. diff --git a/docs/governance.rst b/docs/governance.rst index b3d2228ef..83e48042b 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -141,8 +141,8 @@ 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 enforces. If they reach a concensus that a person shouldn't have a -tedana leadership position, then they should be removed. Of a code of conduct -enforcer as a conflict of interest, then the remaining code of conduct enforcers +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 @@ -173,7 +173,7 @@ and heavily depend on the 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. + 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 From 1aa40a1936cea2c16a204d64a0e594d5a75a1359 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Wed, 18 Nov 2020 21:16:24 -0500 Subject: [PATCH 29/46] Apply suggestions from code review Changed votes from maintainers to contributors and changed voting timelines. Several other style changes or typo fixes. --- docs/contributing.rst | 5 +++-- docs/governance.rst | 11 ++++++----- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 9172e0f1b..fd517807a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -60,7 +60,7 @@ 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) +tedana was developed out of a package known as [multi-echo ICA, ME-ICA, or MEICA](https://github.com/ME-ICA/me-ica ) 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 @@ -103,7 +103,8 @@ 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 +- 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 diff --git a/docs/governance.rst b/docs/governance.rst index 83e48042b..ab5658aa2 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -196,11 +196,12 @@ and heavily depend on the 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. If a PR has a disagreement - that required a vote, there must be at least 15 days from the conclusion - of the first vote before another vote can be triggered. - b) Only Maintainers can vote and each Maintainer gets one vote. - c) A vote ends after 7 working days or when all Maintainers have voted or + 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 From 475c80c6c29e7cdde5385283304fc173f0c82a1c Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Wed, 18 Nov 2020 21:41:48 -0500 Subject: [PATCH 30/46] Update docs/governance.rst added tentative steering committee --- docs/governance.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/governance.rst b/docs/governance.rst index ab5658aa2..e10e42969 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -81,17 +81,19 @@ Steering committee The steering committee is made up of a subset of maintainers who help guide the project. Current Steering Committee members: - +----------------------------------------------+ - | `Dan Handwerker`_ (@handwerkerd) (tentative) | - +----------------------------------------------+ - | Your name here! | - +----------------------------------------------+ - | Your name here! | - +----------------------------------------------+ - | Your name here! | - +----------------------------------------------+ - | Your name here! | - +----------------------------------------------+ + +--------------------------------------+ + | `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 From c7afe122770a0e681fd63e153a9f7bee8d65c696 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Mon, 23 Nov 2020 13:42:19 -0500 Subject: [PATCH 31/46] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Several language changes for clarity & added Javier as a Maintainer. Co-authored-by: Eneko Uruñuela <13706448+eurunuela@users.noreply.github.com> --- docs/contributing.rst | 9 +++++---- docs/governance.rst | 5 ++++- docs/roadmap.rst | 4 ++-- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index fd517807a..522f739ec 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -47,7 +47,7 @@ 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. [Acquisition related details can be found in the tedana Documentation](https://tedana.readthedocs.io/en/latest/acquisition.html). Combining echoes ---------------- @@ -72,7 +72,8 @@ processing) and noise (defined here as changes unrelated to neural processing, i.e. motion, cardiac, respiration). tedana is primarily intended to work on volume data, that is, data that is -still in structured voxel space. Surface-based denoising is not currently +still in structured voxel space. This is because several of the current 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 should be written so that it is a possible option in the future. @@ -82,8 +83,8 @@ that use information across multiple runs are welcome. Visualization ------------- -Though tedana does not provide a GUI for inspecting results, it does produce -figures as part of the processing stream. These figures are intended to help +As part of the processing stream, tedana provides figures and an +HTML-based GUI 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. diff --git a/docs/governance.rst b/docs/governance.rst index e10e42969..8ea6bdd2d 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -37,7 +37,7 @@ following system with several goals in mind: 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 for our to improve +who want to take on a leadership role as well as ideas to improve this structure. Leadership @@ -66,6 +66,8 @@ Maintainer +-----------------------------------+ | `Elizabeth DuPre`_ (@emdupre) | +-----------------------------------+ + | `Javier Gonzalez-Castillo`_ (@javiergcas) | + +-----------------------------------+ | `Dan Handwerker`_ (@handwerkerd) | +-----------------------------------+ | `Taylor Salo`_ (@tsalo) | @@ -237,6 +239,7 @@ 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 .. _Taylor Salo: https://tsalo.github.io .. _Joshua Teves: https://github.com/jbteves diff --git a/docs/roadmap.rst b/docs/roadmap.rst index 43dc4d711..e38ef9136 100644 --- a/docs/roadmap.rst +++ b/docs/roadmap.rst @@ -10,8 +10,8 @@ denoising method that was originally defined in ME-ICA 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 people use the tedana -software. +communal resources for multi-echo fMRI, whether or not they +directly involve the tedana software. A more detailed `project scope is here `_ From ff7f48b04978fbcc3a837c137ff750b487af80d8 Mon Sep 17 00:00:00 2001 From: Joshua Teves Date: Mon, 23 Nov 2020 15:52:42 -0500 Subject: [PATCH 32/46] Adds steering committee link --- docs/governance.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index e10e42969..39c0092d5 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -78,7 +78,7 @@ Maintainer +-----------------------------------+ Steering committee - The steering committee is made up of a subset of maintainers who help guide + The :ref:`Steering Committee` is made up of a subset of maintainers who help guide the project. Current Steering Committee members: +--------------------------------------+ @@ -211,6 +211,8 @@ and heavily depend on the 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 From 0e43a1f87bc9e382b72f7ef0d520b447b4c10a0f Mon Sep 17 00:00:00 2001 From: Joshua Teves Date: Mon, 23 Nov 2020 15:58:09 -0500 Subject: [PATCH 33/46] Fix accidental heading --- docs/governance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index fa41338d7..0f56a717c 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -200,7 +200,7 @@ and heavily depend on the 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 + 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. From 504420ade4f9ef2960e9389b4175b33070130cf4 Mon Sep 17 00:00:00 2001 From: Joshua Teves Date: Mon, 23 Nov 2020 16:23:27 -0500 Subject: [PATCH 34/46] Fixes missing CoC link --- docs/governance.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/governance.rst b/docs/governance.rst index 0f56a717c..548aab80d 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -125,11 +125,8 @@ Focused Leadership Roles | 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`_ & another volunteer - | A person or people someone can go to if they want to report a code of conduct violation - | If this is one person, that person should NOT be on the steering committee - | If this is more than one person, at least one should not be on the steering committee - | Ideal is someone who cares about tedana but DOESN’T know contributors well enough to say, ”Person X would never do that” + - | Enforcer(s) of the `code of conduct`_: `Elizabeth DuPre`_ & `Dan Handwerker`_ & another volunteer + | People someone can go to if they want to report a code of conduct violation Changing leaders ```````````````` @@ -247,6 +244,7 @@ The outcome of a vote is based on a simple majority. .. _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> From 010a2055a4b476863060fcb706bf22ceba4ea8b5 Mon Sep 17 00:00:00 2001 From: Joshua Teves Date: Mon, 23 Nov 2020 17:10:55 -0500 Subject: [PATCH 35/46] Add @smoia as a CoC enforcer --- docs/governance.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/governance.rst b/docs/governance.rst index 548aab80d..45938f8bd 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -125,7 +125,7 @@ Focused Leadership Roles | 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`_ & another volunteer + - | 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 @@ -240,6 +240,7 @@ The outcome of a vote is based on a simple majority. .. _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 From 663f9add3b7d6161b412effe23e86bf1e89bd6b7 Mon Sep 17 00:00:00 2001 From: Joshua Teves Date: Tue, 24 Nov 2020 10:52:50 -0500 Subject: [PATCH 36/46] Shortened line length and fixed typos --- docs/governance.rst | 304 ++++++++++++++++++++++++++------------------ 1 file changed, 177 insertions(+), 127 deletions(-) diff --git a/docs/governance.rst b/docs/governance.rst index 45938f8bd..915b2a44e 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -2,18 +2,23 @@ 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``. +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 +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. We developed the +leader role. +Even if such a person was interested, it may not benefit the +project to overly rely on the existence of one person. +We developed the following system with several goals in mind: - Grow the community. @@ -36,7 +41,8 @@ following system with several goals in mind: - 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 +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. @@ -44,183 +50,225 @@ 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. + 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 Contributor 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) | - +-----------------------------------+ + A Contributor 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) | - +-----------------------------------+ - | `Kirstie Whitaker`_ (@KirstieJane)| - +-----------------------------------+ + +-------------------------------------------+ + | `Dan Handwerker`_ (@handwerkerd) | + +-------------------------------------------+ + | `Taylor Salo`_ (@tsalo) | + +-------------------------------------------+ + | `Joshua Teves`_ (@jbteves) | + +-------------------------------------------+ + | `Eneko Uruñuela`_ (@eurunuela) | + +-------------------------------------------+ + | `Kirstie Whitaker`_ (@KirstieJane) | + +-------------------------------------------+ Steering committee - The :ref:`Steering Committee` is made up of a subset of maintainers who help guide - the project. Current Steering Committee members: + The :ref:`Steering Committee` is made up of a subset of maintainers who + help guide the project. + + Current Steering Committee members: +--------------------------------------+ - | `Logan Dowdle`_ (@dowdlelt) | + | `Logan Dowdle`_ (@dowdlelt) | +--------------------------------------+ - | `Elizabeth DuPre`_ (@emdupre) | + | `Elizabeth DuPre`_ (@emdupre) | +--------------------------------------+ - | `Dan Handwerker`_ (@handwerkerd) | + | `Dan Handwerker`_ (@handwerkerd) | +--------------------------------------+ - | `Taylor Salo`_ (@tsalo) | + | `Taylor Salo`_ (@tsalo) | +--------------------------------------+ - | `Joshua Teves`_ (@jbteves) | + | `Joshua Teves`_ (@jbteves) | +--------------------------------------+ - | `Eneko Uruñuela`_ (@eurunuela) | + | `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 - + 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 + | 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 leader `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 + | 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 leader `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 leader `Elizabeth DuPre`_ & `Joshua Teves`_ - | Helps make sure tedana is following best practices for Python code design, testing, and communication for issues/pull requests etc. + | 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 + | 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 + | 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 + | 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 enforces. 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. +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 +`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). +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 + 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 + 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. + 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. + 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 +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 dismissing their - review, so that the PR can be approved and merged, then the disagreement - will be resolved with a vote. + solution that would lead to: + (1) The author closing the PR without merging + (2) The reviewer accepting requested changes or + (3) The 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. + 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. + 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: 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 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: +The steering committee can decide: - An issue should be prioritized for wider communal discussion. - A a pull request requires more discussion or reviews than standard before merging. @@ -229,9 +277,11 @@ The steering committee can decide: 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. +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. From 21fe0c99ff83a720c02a8e7844e313e7a0866d02 Mon Sep 17 00:00:00 2001 From: Joshua Teves Date: Tue, 24 Nov 2020 11:02:57 -0500 Subject: [PATCH 37/46] Fixes rst mistakes from myself --- docs/governance.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/governance.rst b/docs/governance.rst index 915b2a44e..bd2d019d1 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -132,8 +132,7 @@ Focused Leadership Roles 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 leader `Eneko Uruñuela`_ (Decomposition) & - `Dan Handwerker`_ (Metrics & Decision Tree) + - | Processing algorithms leader `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) @@ -152,8 +151,7 @@ Focused Leadership Roles - | 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`_ + - | 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 @@ -196,6 +194,7 @@ and heavily depend on the 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. @@ -231,12 +230,13 @@ and heavily depend on the 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 dismissing their review, so that the PR can be approved and - merged, then the disagreement - will be resolved with a vote. + 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. @@ -255,8 +255,7 @@ and heavily depend on the 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: Steering Committee ``````````````````` @@ -269,6 +268,7 @@ decisions without community input. The steering committee can decide: + - An issue should be prioritized for wider communal discussion. - A a pull request requires more discussion or reviews than standard before merging. From d1cc31f7ff5915d83cdd016d7e577e980669b1c4 Mon Sep 17 00:00:00 2001 From: Joshua Teves Date: Tue, 24 Nov 2020 11:04:35 -0500 Subject: [PATCH 38/46] Fixes missing colons --- docs/governance.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/governance.rst b/docs/governance.rst index bd2d019d1..7bde46ea2 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -127,28 +127,28 @@ Focused Leadership Roles | 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`_ + - | 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 leader `Eneko Uruñuela`_ (Decomposition) & `Dan Handwerker`_ (Metrics & Decision Tree) + - | 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 leader `Elizabeth DuPre`_ & `Joshua Teves`_ + - | 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`_ + - | Communications leader: `Joshua Teves`_ | Mailing list manager & other outward-facing communication about the project - - | New contributors leader `Taylor Salo`_ + - | 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`_ + - | 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`_ From da65abfb4c22801c6578f93e3b257b6765557d87 Mon Sep 17 00:00:00 2001 From: Joshua Teves Date: Tue, 24 Nov 2020 11:24:12 -0500 Subject: [PATCH 39/46] Removes trailing whitespace --- docs/governance.rst | 99 +++++++++++++++++++++++---------------------- 1 file changed, 51 insertions(+), 48 deletions(-) diff --git a/docs/governance.rst b/docs/governance.rst index 7bde46ea2..e61033212 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -12,7 +12,7 @@ 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 +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. @@ -54,18 +54,18 @@ Contributor 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 + 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 + Contributors also have the option to be added to the Zenodo file which may be used for authorship credit for tedana. - + Maintainer A Contributor 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 + 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 @@ -75,7 +75,7 @@ Maintainer Current Maintainers: +-------------------------------------------+ - | `Logan Dowdle`_ (@dowdlelt) | + | `Logan Dowdle`_ (@dowdlelt) | +-------------------------------------------+ | `Elizabeth DuPre`_ (@emdupre) | +-------------------------------------------+ @@ -99,7 +99,7 @@ Steering committee Current Steering Committee members: +--------------------------------------+ - | `Logan Dowdle`_ (@dowdlelt) | + | `Logan Dowdle`_ (@dowdlelt) | +--------------------------------------+ | `Elizabeth DuPre`_ (@emdupre) | +--------------------------------------+ @@ -118,41 +118,44 @@ Focused Leadership Roles 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 + 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 + | 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 + + | Someone who can make sure calculations fit within our understanding of MR physics - | Someone who can either answer MRI physics questions related to + | 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 + + | 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 + | 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 + | 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 + | 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 + | 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 + | People someone can go to if they want to report a code of conduct violation Changing leaders @@ -166,21 +169,21 @@ 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 +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 +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 +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 `_, +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 @@ -188,18 +191,18 @@ and heavily depend on the 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 +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 +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 + 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 + 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 @@ -207,7 +210,7 @@ and heavily depend on the 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 + 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. @@ -223,33 +226,33 @@ and heavily depend on the 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 + 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 +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: + solution that would lead to: (1) The author closing the PR without merging - (2) The reviewer accepting requested changes or - (3) The dismissing their review, so that the PR can be approved and + (2) The reviewer accepting requested changes or + (3) The 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 + 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 + 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 + 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 + 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 + 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. @@ -260,10 +263,10 @@ and heavily depend on the Steering Committee ``````````````````` The steering committee steers. -The goal of the steering committee is to help guide the direction of the +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 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. @@ -278,7 +281,7 @@ The steering committee can decide: - 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 +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. From 5b12ae66ba276de1ff26a26eee03be63522e219e Mon Sep 17 00:00:00 2001 From: Joshua Teves Date: Tue, 24 Nov 2020 11:55:50 -0500 Subject: [PATCH 40/46] Fixes periods and whitespace in roadmap.rst --- docs/roadmap.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/roadmap.rst b/docs/roadmap.rst index e38ef9136..2eb007720 100644 --- a/docs/roadmap.rst +++ b/docs/roadmap.rst @@ -5,13 +5,14 @@ Project vision -------------- ``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. +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 `_ From 0bbf8cff422561614c63be9690e4def2826462ef Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 24 Nov 2020 16:47:26 -0500 Subject: [PATCH 41/46] Text cleaning. Removed Kirstie as a maintainer --- docs/contributing.rst | 10 +++++++--- docs/governance.rst | 6 ++---- docs/roadmap.rst | 2 +- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 522f739ec..0fd38f8c7 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -47,7 +47,9 @@ 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](https://tedana.readthedocs.io/en/latest/acquisition.html). +tedana. `Acquisition related details can be found in the tedana Documentation.`_ + +.. _Acquisition related details can be found in the tedana Documentation.: https://tedana.readthedocs.io/en/latest/acquisition.html Combining echoes ---------------- @@ -60,7 +62,7 @@ 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](https://github.com/ME-ICA/me-ica ) +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 @@ -72,7 +74,7 @@ processing) and noise (defined here as changes unrelated to neural processing, i.e. 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 current used denoising metrics rely on spatial continuity, and they have not yet been updated to consider continuity over cortical vertices. +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 should be written so that it is a possible option in the future. @@ -80,6 +82,8 @@ 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 ------------- diff --git a/docs/governance.rst b/docs/governance.rst index e61033212..f9f96c5be 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -28,7 +28,7 @@ following system with several goals in mind: - 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 responsabilies into multiple smaller roles also + Dividing leadership responsabilities 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: @@ -62,7 +62,7 @@ Contributor Maintainer - A Contributor is responsible for the long term health of the project and + A Maintiner 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 @@ -89,8 +89,6 @@ Maintainer +-------------------------------------------+ | `Eneko Uruñuela`_ (@eurunuela) | +-------------------------------------------+ - | `Kirstie Whitaker`_ (@KirstieJane) | - +-------------------------------------------+ Steering committee The :ref:`Steering Committee` is made up of a subset of maintainers who diff --git a/docs/roadmap.rst b/docs/roadmap.rst index 2eb007720..e2a9aa4aa 100644 --- a/docs/roadmap.rst +++ b/docs/roadmap.rst @@ -6,7 +6,7 @@ Project vision ``tedana`` was originally developed as a place for the multi-echo fMRI denoising method that was originally defined in ME-ICA -(`ME-ICA source `_. +(`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. From 205a92cef29e4d69d33ecb84c06b36a14b643725 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 24 Nov 2020 19:11:11 -0500 Subject: [PATCH 42/46] Apply suggestions from code review typo fixes Co-authored-by: Joshua Teves --- docs/contributing.rst | 5 +++-- docs/governance.rst | 4 ++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 0fd38f8c7..1f64fd0a2 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -47,9 +47,10 @@ 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. +Acquisition related details can be found in the `tedana Documentation.`_ -.. _Acquisition related details can be found in the tedana Documentation.: https://tedana.readthedocs.io/en/latest/acquisition.html +.. _tedana Documentation.: https://tedana.readthedocs.io/en/latest/acquisition.html Combining echoes ---------------- diff --git a/docs/governance.rst b/docs/governance.rst index f9f96c5be..4b6f392ca 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -28,7 +28,7 @@ following system with several goals in mind: - 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 responsabilities into multiple smaller roles also + 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: @@ -62,7 +62,7 @@ Contributor Maintainer - A Maintiner is responsible for the long term health of the project and + 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 From 78cf9e8e47ad5b022262a58e0fd1a26946e81557 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Sat, 5 Dec 2020 21:24:22 -0500 Subject: [PATCH 43/46] Apply suggestions from code review typo/working fixes suggested by stalo Co-authored-by: Taylor Salo --- docs/contributing.rst | 4 ++-- docs/governance.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 1f64fd0a2..98ff02f1e 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -25,9 +25,9 @@ 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 +but somewhat distinct, ideas related to multi-echo analysis. This scope includes collecting multi-echo data (Acquisition), combining those echoes together -(Combining), with optional noise removal (Denoising), inspecting the outputs +(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. diff --git a/docs/governance.rst b/docs/governance.rst index 4b6f392ca..6e13f1d47 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -271,7 +271,7 @@ decisions without community input. The steering committee can decide: - An issue should be prioritized for wider communal discussion. -- A a pull request requires more discussion or reviews than standard before +- 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 From 28865e6ce22f8cdd23925424741b211eecf4ea1e Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Sat, 5 Dec 2020 21:26:06 -0500 Subject: [PATCH 44/46] Update docs/contributing.rst grammer fix --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 98ff02f1e..d9a8ae062 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -72,7 +72,7 @@ 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, i.e. motion, cardiac, respiration). +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. From db1aab688faf8086c36676ba57d30fa1f6aa2876 Mon Sep 17 00:00:00 2001 From: Dan Handwerker <7406227+handwerkerd@users.noreply.github.com> Date: Mon, 7 Dec 2020 14:40:40 -0500 Subject: [PATCH 45/46] Apply suggestions from code review Language clarifications from emdupre's review Co-authored-by: Elizabeth DuPre --- docs/contributing.rst | 6 +++--- docs/governance.rst | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index d9a8ae062..09f58bd22 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -35,7 +35,7 @@ are ready for further analyses. Acquisition ----------- -While the development of multi-echo sequences is far beyond the current scope +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 @@ -77,7 +77,7 @@ 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 should be written so that it is a +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 @@ -89,7 +89,7 @@ Visualization ------------- As part of the processing stream, tedana provides figures and an -HTML-based GUI for inspecting results. These are intended to help +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. diff --git a/docs/governance.rst b/docs/governance.rst index 6e13f1d47..d4e3aabd8 100644 --- a/docs/governance.rst +++ b/docs/governance.rst @@ -1,7 +1,7 @@ Governance ========== Governance is a hugely important part of any project. -It is especially important to have clear process and communication channels +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``. @@ -18,7 +18,7 @@ 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. -We developed the +Instead, we developed the following system with several goals in mind: - Grow the community. @@ -234,7 +234,7 @@ and heavily depend on the (1) The author closing the PR without merging (2) The reviewer accepting requested changes or - (3) The dismissing their review, so that the PR can be approved and + (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: From 0a131030ffec4190ba0137e7b6c7f344387783de Mon Sep 17 00:00:00 2001 From: Joshua Teves Date: Mon, 7 Dec 2020 17:01:10 -0500 Subject: [PATCH 46/46] Fix warnings in html make --- docs/contributing.rst | 4 +++- docs/support.rst | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 09f58bd22..6a9436456 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -278,9 +278,11 @@ 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 ----------------- 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`_.