ME-ICA · emdupre · Nov 13, 2018 · Nov 1, 2018 · Nov 1, 2018 · Nov 1, 2018
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,24 +1,57 @@
-# Contributing to tedana
+# Contributing to `tedana`
 
-Welcome to the tedana repository! We're excited you're here and want to contribute.  
+Welcome to the `tedana` repository! We're excited you're here and want to contribute.  
 
-These guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know by opening an [issue][link_issues]!
+These guidelines are designed to make it as easy as possible to get involved.
+If you have any questions that aren't discussed below, please let us know by opening an [issue][link_issues]!
 
-Before you start you'll need to set up a free [GitHub][link_github] account and sign in. Here are some [instructions][link_signupinstructions].
+Before you start you'll need to set up a free [GitHub][link_github] account and sign in.
+Here are some [instructions][link_signupinstructions].
 
 Already know what you're looking for in this guide? Jump to the following sections:
+
 * [Joining the conversation](#joining-the-conversation)
-* [Understanding issue labels](#issue-labels)
+* [Understanding issues, milestones, and project boards](#explaining-issues-milestones-and-project-boards)
 * [Making a change](#making-a-change)
-* [Recognizing contributions](#recognizing-contributions)
+* [Structuring contributions](#style-guide)
+* [Recognizing contributors](#recognizing-contributions)
 
 ## Joining the conversation
 
 `tedana` is a young project maintained by a growing group of enthusiastic developers&mdash; and we're excited to have you join!
 Most of our discussions will take place on open [issues][link_issues].
 We also maintain a [gitter chat room][link_gitter] for more informal conversations and general project updates.
 
-There is significant cross-talk between these two spaces, and we look forward to hearing from you in either venue! As a reminder, we expect all contributions to `tedana` to adhere to our [code of conduct][link_coc].
+There is significant cross-talk between these two spaces, and we look forward to hearing from you in either venue!
+As a reminder, we expect all contributions to `tedana` to adhere to our [code of conduct][link_coc].
+
+## Understanding issues, milestones and project boards
+
+Every project on GitHub uses [issues][link_issues], [milestones][link_milestones],
+and [project boards][link_project_boards] slightly differently.
+
+The following outlines how the ``tedana`` developers think about these different tools.
+
+* **Issues** are individual pieces of work that need to be completed to move the project forwards.
+A general guideline: if you find yourself tempted to write a great big issue that
+is difficult to describe as one unit of work, please consider splitting it into two or more issues.
+
+    Issues are assigned [labels](#issue-labels) which explain how they relate to the overall project's
+    goals and immediate next steps.
+
+* **Milestones** are the link between the issues and the high level strategy for the ``tedana`` project.
+Contributors new and old are encouraged to take a look at the milestones to see how we are progressing
+towards ``tedana``'s shared vision.
+
+    Issues are assigned to these milestones by the maintainers.
+    If you feel that an issue should be assigned to a specific milestone but the maintainers have not done so, just ask!
+    We might have just missed it, or we might not (yet) see how it aligns with the overall project structure.
+    These conversations are important to have, and we are excited to hear your perspective!
+
+* The **project board** is an automated [Kanban board][link_kanban] to keep track of what is currently underway
+(in progress), what has been completed (done), and what remains to be done for a specific release.
+The ``tedana``  maintainers use this board to keep an eye on how tasks are progressing week by week.
+
 
 ### Issue labels
 
@@ -35,7 +68,9 @@ The current list of labels are [here][link_labels] and include:
 
 * [![Enhancement](https://img.shields.io/badge/-enhancement-84b6eb.svg)][link_enhancement] *These issues are asking for enhancements to be added to the project.*
 
-    Please try to make sure that your enhancement is distinct from any others that have already been requested or implemented. If you find one that's similar but there are subtle differences please reference the other request in your issue.
+    Please try to make sure that your enhancement is distinct from any others that have already been requested or implemented.
+    If you find one that's similar but there are subtle differences please reference the other request in your issue.
+
 
 ## Making a change
 
@@ -57,13 +92,43 @@ Make sure to [keep your fork up to date][link_updateupstreamwiki] with the maste
 
 Try to keep the changes focused. We've found that working on a [new branch][link_branches] makes it easier to keep your changes targeted.
 
-When you're creating your pull request, please make sure to review the tedana [style conventions][link_styleguide].
+When you're creating your pull request, please make sure to review the tedana [style conventions](#style-guide).
 
 **4. Submit a [pull request][link_pullrequest].**
 
-A member of the development team will review your changes to confirm that they can be merged into the main codebase.
+A member of the development team will review your changes to confirm that they can be merged into the main code base.
+When opening the pull request, we ask that you follow some [specific conventions](#pull-requests).
+We outline these below.
+
+### Pull Requests
+
+To improve understanding pull requests "at a glance", we encourage the use of several standardized tags.
+When opening a pull request, please use at least one of the following prefixes:
+
+* **[ENH]** for enhancements
+* **[FIX]** for bug fixes
+* **[TST]** for new or updated tests
+* **[DOC]** for new or updated documentation
+* **[STY]** for stylistic changes
+* **[REF]** for refactoring existing code
+* **[BRK]** for changes which break existing builds or tests
+* **[WIP]** for changes which are not yet ready to be merged
 
-## Recognizing contributions
+Pull requests should be submitted early and often!
+If your pull request is not yet ready to be merged, please also include the **[WIP]** prefix.
+This tells the development team that your pull request is a "work-in-progress",
+and that you plan to continue working on it.
+
+## Style Guide
+
+Docstrings should follow [numpydoc][link_numpydoc] convention.
+We encourage extensive documentation.
+
+The code itself should follow [PEP8][link_pep8] convention
+whenever possible, with at most about 500 lines of code (not including docstrings) per script.
+
+
+## Recognizing contributors
 
 We welcome and recognize all contributions from documentation to testing to code development.
 You can see a list of current contributors in the [contributors tab][link_contributors].
@@ -79,22 +144,27 @@ You're awesome. :wave::smiley:
 [link_github]: https://github.com/
 [link_tedana]: https://github.com/ME-ICA/tedana
 [link_signupinstructions]: https://help.github.com/articles/signing-up-for-a-new-github-account
-[link_react]: https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments
+
 [link_issues]: https://github.com/ME-ICA/tedana/issues
+[link_milestones]: https://github.com/ME-ICA/tedana/milestones/
+[link_project_boards]: https://github.com/ME-ICA/tedana/projects
 [link_gitter]: https://gitter.im/me-ica/tedana
 [link_coc]: https://github.com/ME-ICA/tedana/blob/master/Code_of_Conduct.md
-[link_labels]: https://github.com/ME-ICA/tedana/labels
-[link_discussingissues]: https://help.github.com/articles/discussing-projects-in-issues-and-pull-requests
 
+[link_labels]: https://github.com/ME-ICA/tedana/labels
 [link_bugs]: https://github.com/ME-ICA/tedana/labels/bug
 [link_helpwanted]: https://github.com/ME-ICA/tedana/labels/help%20wanted
 [link_enhancement]: https://github.com/ME-ICA/tedana/labels/enhancement
 
+[link_kanban]: https://en.wikipedia.org/wiki/Kanban_board
 [link_pullrequest]: https://help.github.com/articles/creating-a-pull-request/
 [link_fork]: https://help.github.com/articles/fork-a-repo/
 [link_pushpullblog]: https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/
-[link_branches]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
-[link_styleguide]: http://tedana.readthedocs.io/en/latest/contributing.html
 [link_updateupstreamwiki]: https://help.github.com/articles/syncing-a-fork/
-[link_stemmrolemodels]: https://github.com/KirstieJane/STEMMRoleModels
+[link_branches]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
+
+[link_numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html
+[link_pep8]: https://www.python.org/dev/peps/pep-0008/
+
 [link_contributors]: https://github.com/ME-ICA/tedana/graphs/contributors
+[link_stemmrolemodels]: https://github.com/KirstieJane/STEMMRoleModels
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -1,50 +1,170 @@
 Contributing to tedana
 ======================
 
-This document explains how to set up a development environment for contributing
-to tedana and code style conventions we follow within the project.
-For a more general guide to the tedana development, please see our
-`contributing guide`_. Please also follow our `code of conduct`_.
+This document explains contributing to ``tedana`` at a very high level,
+with a focus on project governance and development philosophy.
+For a more practical guide to the tedana development, please see our
+`contributing guide`_.
 
 .. _contributing guide: https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md
-.. _code of conduct: https://github.com/ME-ICA/tedana/blob/master/CODE_OF_CONDUCT.md
 
+Governance
+----------
 
-Style Guide
-===========
+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``.
 
-Code
-````
+```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.
 
-Docstrings should follow `numpydoc`_ convention. We encourage extensive
-documentation.
+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.
 
-The code itself should follow `PEP8`_ convention as much as possible, with at
-most about 500 lines of code (not including docstrings) per script.
+Code of conduct
+```````````````
 
-.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
-.. _PEP8: https://www.python.org/dev/peps/pep-0008/
+All ``tedana`` community members are expected to follow our `code of conduct`_
+during any interaction with the project.
+That includes---but is not limited to---online conversations,
+in-person workshops or development sprints, and when giving talks about the software.
 
-Pull Requests
-`````````````
+As it is 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.
 
-We encourage the use of standardized tags for categorizing pull requests.
-When opening a pull request, please use one of the following prefixes:
+.. _code of conduct: https://github.com/ME-ICA/tedana/blob/master/Code_of_Conduct.md
 
-    + **[ENH]** for enhancements
-    + **[FIX]** for bug fixes
-    + **[TST]** for new or updated tests
-    + **[DOC]** for new or updated documentation
-    + **[STY]** for stylistic changes
-    + **[RF]** for refactoring existing code
+```tedana``'s development philosophy
+--------------------------------------
 
-Pull requests should be submitted early and often!
-If your pull request is not yet ready to be merged, please also include the **[WIP]** prefix.
-This tells the development team that your pull request is a "work-in-progress",
-and that you plan to continue working on it.
+In contributing to any open source proect,
+we have found that it is hugely valuable to understand the core maintainers's development philosophy.
+In order to aid other contributors in onboarding to ``tedana`` development,
+we have therefore laid out our shared opinion on several major decision points.
+These are:
+
+#. :ref:`exposing options to the user`,
+#. :ref:`prioritizing project developments`,
+#. :ref:`future-proofing for continuous development`, and
+#. :ref:`when to release new software versions`
+
+
+.. _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.
+In doing so, we have made a decision to embrace defaults which support the broadest base of users.
+For example, the choice of a widely-accepted ICA cost function,
+or a well-validated dimensionality reduction threshold for retaining PCA components.
+These two parts of the ``tedana``  processing pipeline have huge impact on the results,
+and which are difficult for individual researchers to form an opinion on.
+
+The ``tedana`` "opinionated approach" is therefore to provide reasonable defaults,
+and to hide some options from the top level workflows.
+
+This decision has two key benefits:
+1. By default, users should get high quality results from running the pipelines, and
+2. The work required of the ``tedana``  developers to maintain the project is more focused and somewhat restricted.
+
+It is important to note that ``tedana``  is shipped under `an LGPL2 license`_ which means that
+the code can---at all times---be cloned and re-used by anyone for any purpose.
+"Power users" will always be able to access and extend all of the options available.
+We encourage those users to feed back their work into ``tedana``  development,
+particularly if they have good evidence for updating the default values.
+
+We understand that it is possible to build the software to provide more
+options within the existing framework, but have chosen to focus on `the 80 percent use cases`_.
+
+You can provide feedback on this philosophy through any of the channels
+listed on the ``tedana``  :doc:`support` page.
+
+.. _an LGPL2 license: https://github.com/ME-ICA/tedana/blob/master/LICENSE
+.. _the 80 percent use cases: https://en.wikipedia.org/wiki/Pareto_principle#In_software
+
+
+.. _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 prioritize what work needs to be completed.
+We have outlined our goals for ``tedana`` in our :doc:`roadmap`,
+which we encourage all contributors to read and give feedback on.
+Feedback can be provided through any of the channels listed on our :doc:`support` page.
+
+In order to more directly map between our :doc:`roadmap` and ongoing `project issues`_,
+we have also created `milestones in the github repository`_.
+
+.. _project issues: https://github.com/ME-ICA/tedana/issues
+.. _milestones in the github repository: https://github.com/me-ica/tedana/milestones
+
+This allows us to
+
+1. Label individual issues as supporting specific aims and
+2. Helps us to measure progress towards each aim's concrete deliverable(s).
+
+
+.. _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.
+In order to focus our limited time, we have made the decision to not let future possibilities limit
+or overcomplicate the most immediately required features.
+That is, to `not let the perfect be the enemy of the good`_.
+
+.. _not let the perfect be the enemy of the good: https://en.wikipedia.org/wiki/Perfect_is_the_enemy_of_good
+
+While this stance will almost certainly yield ongoing refactoring as the scope of the software expands,
+the team's commitment to transparency, reproducibility, and extensive testing
+mean that this work should be relatively manageable.
+
+We hope that the lessons we learn building something useful in the short term will be
+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.
+
+To try to be more concrete, if a change to the project substantially changes the user's experience
+of working with the ``tedana``  module, it would be helpful to release an updated version.
+Additional functionality and bug fixes are very clear opportunities to release updated versions,
+but there will be many other reasons to update the software as hosted on `PyPi`_.
+
+.. _PyPi: https://pypi.org/project/tedana/
+
+To give two concrete examples of slightly less obvious cases:
+
+1. A substantial update to the documentation that makes ``tedana``  easier to use **would** count as
+a substantial change to ``tedana``  and a new release should be considered.
+2. In contrast, updating code coverage with additional unit tests does not affect the
+**user's** experience with ``tedana``  and therefore does not require a new release.
+
+Any member of the ``tedana``  community can propose that a new version is released.
+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`.
+
+
+.. _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/index.rst b/docs/index.rst
@@ -43,19 +43,15 @@ multi-echo functional magnetic resonance imaging (fMRI) data.
 About
 -----
 
+.. image:: https://user-images.githubusercontent.com/7406227/40031156-57b7cbb8-57bc-11e8-8c51-5b29f2e86a48.png
+  :target: http://tedana.readthedocs.io/
+
 ``tedana`` originally came about as a part of the `ME-ICA`_ pipeline.
 The ME-ICA pipeline originally performed both pre-processing and TE-dependent
 analysis of multi-echo fMRI data; however, ``tedana`` now assumes that you're
 working with data which has been previously preprocessed.
-If you're in need of a preprocessing pipeline, we recommend
-`fmriprep`_, which has been tested
-for compatibility with multi-echo fMRI data and ``tedana``.
-
-.. image:: https://user-images.githubusercontent.com/7406227/40031156-57b7cbb8-57bc-11e8-8c51-5b29f2e86a48.png
-  :target: http://tedana.readthedocs.io/
 
 .. _ME-ICA: https://github.com/me-ica/me-ica
-.. _fmriprep: https://github.com/poldracklab/fmriprep/
 
 Citations
 ---------
@@ -134,8 +130,9 @@ tedana is licensed under GNU Lesser General Public License version 2.1.
    usage
    approach
    outputs
-   support
    contributing
+   roadmap
+   support
    api
 
 Indices and tables