[DOC] Explain contributing philosophy

docs/contributing.rst

@@ -1,50 +1,171 @@
 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 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``  `get in touch`_ 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
+.. _get in touch: https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md#joining-the-conversation
+
+
+.. _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 prioritise what work needs to be completed.
+We have outlined our goals for ``tedana`` in our :doc:`roadmap`,
+which we encourage all new contributors to read and `give feedback`_ on.
+
+In order to more directly map between our :doc:`roadmap` and ongoing `project issues`_,
+we have also created `milestones in the github repository`_.
+
+.. _give feedback: https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md#joining-the-conversation
+.. _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