Merge pull request #758 from tripal/756-consolidate-docs

756 consolidate docs

CONTRIBUTING.md

@@ -1,126 +1 @@
-# Guidelines for Contribution to Tripal
-
-The following guidelines are meant to encourage contribution to Tripal source-code on GitHub by making the process open, transparent and collaborative. If you have any feedback including suggestions for improvement or constructive criticism, please [comment on the github issue](https://github.com/tripal/tripal/issues/344). **These guidelines apply to everyone contributing to Tripal whether it's your first time (Welcome!) or project management committee members.**
-
-**Note:** _These guidelines are specifically for contributing to_ [_https://github.com/tripal/tripal_](https://github.com/tripal/tripal)_. However, we encourage all Tripal extension modules to consider following these guidelines to foster collaboration among the greater Tripal Community._
-
-Guidelines serve as suggestions ( **should** ) or requirements (**must).** _When the word "should" is used in the text below, the stated policy is expected but there may be minor exceptions.  When the word "must" is used there are no exceptions to the stated policy._
-
-## Github Communication Tips
-
-- Don't be afraid to mention people (@username) who are knowledgeable on the topic or invested.*- We are academics and overcommitted, it's too easy for issues to go unanswered.
-  - Likewise, don't be shy about bumping an issue if no one responds after a few days.  Balancing responsibilities is hard.
-- Want to get more involved? Issues marked with "Good beginner issue" are a good place to start if you want to try your hand at submitting a PR.
-- Everyone is encouraged/welcome to comment on the issue queue!** Tell us if you
-    - are experiencing the same problem
-    - have tried a suggested fix
-    - know of a potential solution or work-around
-    - have an opinion, idea or feedback of any kind!
-- Be kind when interacting with others on github!** (see Code of Conduct below for further guidelines). We want to foster a welcoming, inclusive community!
-    - Constructive criticism is welcome and encouraged but should be worded such that it is helpful :-) Direct criticism towards the idea or solution rather than the person and focus on alternatives or improvements.
-
-## Bugs
-
-- Every bug **should** be reported as a github issue.
-  - Even if a bug is found by a committer who intends to fix it themselves immediately, they **should** create an issue and assign it to themselves to show their intent.
-- Please follow the issue templates as best you can.  This information makes discussion easier and helps us resolve the problem faster.
-  - Also provide as much information as possible :-)  Screenshots or links to the issue on a development site can go a long way!
-- Bonus points for unit tests to ensure the bug does not return :-)
-
-## Feature Requests
-
-- Every feature request should start as an issue so that discussion is encouraged :-)**
-- Please provide the following information (bold is required; underlined strengthens your argument):
-    - **Use Case:** fully describe why you need/want this feature
-    - Generally Applicable: Why do you feel this is generally applicable? Suggest other use cases if possible. Mention (@) others that might want/need this feature.
-    - Implementation: Describe a possible implementation. Bonus points for configuration, use of ontologies, ease of use, permission control, security considerations
-- All features **should** be optional so that Tripal admin can choose to make it available to their users.
-    - When applicable, new features should be designed such that tripal-site admin can disable them.
-    - Bonus points: for making new features configurable and easily themed.
-- Feature requests will be voted on by the project management and advisory/steering committees to determine if it should be included in core, an existing extension module or it's own extension module.
-    - Votes should be based on whether this feature is generally applicable and doesn't exclude existing users and not be biased by the needs of your own Tripal site.
-- If a feature isn't suitable for inclusion within Tripal core, use the issue discussion as a springboard to create a Tripal extension module!
-
-**Note:** _In the future there will be a set of guidelines for what should be included in core. This will make the process of requesting new features more streamlined, inclusive and transparent._
-
-## Pull Request (PR) Guideline
-
-The goal of this document is to make it easy for **A)** contributors to make pull requests that will be accepted, and **B)** Tripal committers to determine if a pull request should be accepted.
-
-- PRs that address a specific issue **must** link to the related issue page.
-  - Really in almost every case, there should be an issue for a PR.  This allows feedback and discussion before the coding happens.  Not grounds to reject, but encourage users to create issues at start of their PR.  Better late than never :).
-- Each PR **must** be tested/approved by at least 2 users with at least one user being a "trusted committer."
-  - Testers **should** describe how the testing was performed if applicable (allows others to replicate the test).
-  - Tripal's guiding philosophy is to encourage open contribution.  With this in mind, committers should **work with contributors** to resolve issues in their PRs.  PRs that will not be merged should be closed, **transparently citing** the reason for closure.  In an ideal world, features that would be closed are discouraged at the **issue phase** before the code is written!
-  - The pull request branch should be deleted after merging (if not from a forked repository) by the person who performs the merge.
-- PRs that include new functionality **must** also provide Unit Tests.
-  - Tests **must** test the new functionality added.
-  - Bonus points for testing all surrounding functionality.
-    - _Note: testing surrounding functionality is highly encouraged if the submitter is on the PMC ;-)_
-  - For example, when adding feature X to custom tables, the PR must include tests for feature X and we would be greatly appreciative if it included tests for custom tables in general :-D.
-- PRs **should** pass all Travis-CI tests before they are merged.
-- Branches **should** follow the following format:
-    - [issue\_number]-[tripal\_version]-[short\_description]
-  - tripal\_version being Tv2, Tv3, etc.
-  - "-[short\_description]" being optional but highly encouraged
-- **Must** follow Drupal code standards: [https://www.drupal.org/docs/develop/standards](https://www.drupal.org/docs/develop/standards)
-- PRs for new feature should remain open until adequately discussed (see guidelines below) and approved by a vote (all members of the PMC must vote in favour).
-
-**Note:** _See the Tripal PR Tutorial for more guidance on how to actually create a PR if contribution via github is new to you (_ [_KnowPulse workflow for inspiration_](https://github.com/UofS-Pulse-Binfo/KnowPulse/blob/master/Workflow.md)_)_
-
-## General Project Management
-
-- **Every task related to Tripal should be in github, either as it's own issue or grouped with like tasks into a single issue.** This effectively puts our todo list on github making it transparent to anyone who wants to help. It has the benefit of showing how active our community is, keeps everyone informed with where Tripal is headed and makes it easy for others to chime in with experience, comments and support.
-- **Guidelines for Tagging Issues:**
-    - The first committer who comments on an issue should tag it with the version of Tripal it applies to.
-    - Issues with a suggested fix or work-around should be tagged with "Fix Required" to let others know a PR is needed.
-    - Only tag an issue with "bug" once it has been shown to be reproducible. If it's not reproducible by a committer but you feel it is a bug then tag it as "potential bug".
-    - If multiple users have commented that a bug affects them, tag it as "affects multiple users".
-    - Issues that require a PR and someone with relatively little Tripal experience could fix should be tagged with "Good beginner issue"
-    - All feature requests should be tagged as an "enhancement"
-    - If you are the first reviewer to confirm a PR works, tag it with "Reviewer #1 Approval"
-- **Guidelines for Discussion:**
-    - No requirement for discussion (still requires 2 reviews): Minor bug fixes, changes to inline comments, addition of unit tests, minor code typos
-    - Requires Discussion: Major changes, new features, and issue at the discretion of the PMC
-      - Add the "discussion" tag to any issue requiring discussion
-      - Discussion Tag is removed when adequate discussion has taken place (at the discretion of the person who added the tag)
-      - Additionally, new features require that all members of the PMC have had a chance to contribute to the discussion and feel satisfied.
-- Please use the **assignment** feature to clarify who will be contributing the code to prevent duplication of effort.
-    - When assigning yourself, comment on what your timeline is. This allows others to jump in if they have time sooner.
-    - If you would like to **take over a PR assigned to someone else** , comment asking for an update and offer your services.
-    - If the author of the issue plans on contributing the fix themselves but is not a committer, they should indicate that in the issue.  A committer will assign them the issue.
-- When you start working on an issue, you **should** create the branch and push to it regularly. If you are working on a fork, you're **encouraged** to link to it in the issue.
-    - Committers can work on a fork or directly.  If the branch is on tripal/tripal, then other committers should contribute via PR unless otherwise agreed
-- If an issue is identified as being relevant to another repository (ie a tripal module, not core), a new issue **should** be created, cross referenced, and the original issue should be closed encouraging discussion in the module.
-
-## Code of Conduct
-
-- Be nice!  If that's insufficient, Tripal community defers to https://www.contributor-covenant.org/
-
-## Testing/CI
-
-Exhaustive guides to testing are available at tripal.info (here for now: [https://www.bradfordcondon.com/2018/05/02/tripal\_testing\_guidelines/](https://www.bradfordcondon.com/2018/05/02/tripal_testing_guidelines/)).  Below are guiding principles.
-
-- All tests pass.
-- Tests don't modify db: use transactions and factories.
-- Tests are organized properly: by submodule and function.
-- Tests run quietly.
-
-## Changes to this Document
-
-These guidelines are binding to the Tripal Community. If you have comments, suggestions or constructive criticism please bring it up in a [comment on the github issue](https://github.com/tripal/tripal/issues/344). Changes to this document will be made after adequate discussion has occurred and the project management committee has voted in favour of the change.
-
-# Tripal Governance
-
-The above document makes us a sort of hybrid between a [meritocracy and liberal contribution model](https://opensource.guide/leadership-and-governance/#what-are-some-of-the-common-governance-structures-for-open-source-projects).
-
-
-The Tripal project recognizes these roles:
-
-- Users - They have downloaded Tripal!  Maybe they even have a site!
-- Contributors - contributing!  Code, comments, discussion, questions, bug reports.
-- Committers - write access to the repository
-- PMC - Makes **code relevant** decisions.
-- Oversight committee - Makes **policy leve** decisions.  This may overlap with PMC, but the idea is the oversight committee includes parties who are **not necessarily coders** and therefore not reviewing Pull requests etc.
-
-More guidelines coming soon.
+Please see the [Tripal online documentation](https://tripal.readthedocs.io/en/latest/dev_guide/contributing.html) for more information about contributing to Tripal and Tripal governance.

docs/README.md

@@ -1,49 +1 @@
-The Tripal documentation is written in [**Restructured Text**](http://docutils.sourceforge.net/rst.html), compiled with [Sphinx](http://www.sphinx-doc.org/en/master/usage/quickstart.html), and built/hosted with [ReadTheDocs](https://readthedocs.org/).  This directory, when compiled, is hosted at https://tripal.readthedocs.io/en/latest/
-
-For minor changes, you can simply [Edit the file using the Github editor](https://help.github.com/articles/editing-files-in-your-repository/), which will allow you to make a Pull Request.  Once approved, your changes will be reflected in the documentation automatically! 
-
-# Guide
-
-### Install Sphinx
-For minor changes, you don't need to build the documentation!  If you want to see how your changes will look on the built site, however, you will need Sphinx installed.
-
-For more information, please see the Sphinx setup guide:
-http://www.sphinx-doc.org/en/master/usage/quickstart.html
-
-
-### Building your changes
-
-For more extensive edits, or when contributing new guides, you should build the documentation locally. From the `docs` root (eg `/var/www/html/sites/all/modules/tripal/docs/`, execute `make html`.  The built site will be in `docs/_build/html/index.html`.
-
-### Tripal conventions
-Please follow these guidelines when updating our docs. Let us know if you have any questions or something isn't clear.
-
-Please place images in the same folder as the guide text file, following the convention [file_name].[n].[optional description].[extension].  For example, `configuring_page_display.3.rearrange.png` or `configuring_page_display.1.png` are both located in `docs/user_guide/` and are part of the `configuring_page_display.rst` guide.
-
-We currently use the following syntax:
-```
-Title of File (using title case)
-=================================
-
-Introduction text.
-
-Section Title
--------------
-
-We use double backticks to indicate ``inline-code`` including file names, function and method names, paths, etc.
-
-Longer code-blocks should begin with the ``.. code-block:: [type]`` directive and should be indented at least one 
-level. There should also be a blank line before and after it as shown below.
-
-.. code-block:: sql
-  if ($needs_documentation) {
-      use $these_guidelines;
-      $contribute_docs = $appreciated;
-  }
-
-Section 1.1 Title
-^^^^^^^^^^^^^^^^^
-
-The use of appropriate sections makes reading documentation and later specific details easier. Sub sections such 
-as this one will be hidden unless the main section is already selected.
-```
+Please see the [Tripal online documentation](https://tripal.readthedocs.io/en/latest/dev_guide/contributing.html) for contribution instructions.

docs/dev_guide.rst

@@ -15,4 +15,5 @@ Developer's Guide
    dev_guide/exporting_field_settings
    dev_guide/custom_data_loader
    dev_guide/custom_web_services
+   dev_guide/contributing
    dev_guide/tutorials

docs/dev_guide/contributing.rst

@@ -0,0 +1,14 @@
+Contributing to Tripal Core Code
+================================
+
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Table of Contents
+
+
+   contributing/pull_requests
+   contributing/tests
+   contributing/documentation
+   contributing/governance

docs/dev_guide/contributing/documentation.rst

@@ -0,0 +1,62 @@
+Contributing to the Documentation
+==================================
+
+The Tripal documentation is written in `**Restructured Text** <http://docutils.sourceforge.net/rst.html>`_, compiled with `Sphinx <http://www.sphinx-doc.org/en/master/usage/quickstart.html>`_, and built/hosted with `ReadTheDocs  <https://readthedocs.org/>`_.  The ``docs`` directory, when compiled, is hosted at https://tripal.readthedocs.io/en/latest/.
+
+For minor changes, you can simply `Edit the file using the Github editor <https://help.github.com/articles/editing-files-in-your-repository/>`_, which will allow you to make a Pull Request.  Once approved, your changes will be reflected in the documentation automatically!
+
+Guide
+------
+
+
+Install Sphinx
+~~~~~~~~~~~~~~~~~
+
+For minor changes, you don't need to build the documentation!  If you want to see how your changes will look on the built site, however, you will need Sphinx installed.
+
+For more information, please see the Sphinx setup guide:
+http://www.sphinx-doc.org/en/master/usage/quickstart.html
+
+
+Building your changes
+~~~~~~~~~~~~~~~~~~~~~~~
+
+
+For more extensive edits, or when contributing new guides, you should build the documentation locally. From the ``docs`` root (eg ``/var/www/html/sites/all/modules/tripal/docs/``, execute ``make html``.  The built site will be in ``docs/_build/html/index.html``.
+
+Tripal conventions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Please follow these guidelines when updating our docs. Let us know if you have any questions or something isn't clear.
+
+Please place images in the same folder as the guide text file, following the convention [file_name].[n].[optional description].[extension].  For example, ``configuring_page_display.3.rearrange.png`` or ``configuring_page_display.1.png`` are both located in ``docs/user_guide/`` and are part of the ``configuring_page_display.rst`` guide.
+
+We currently use the following syntax:
+
+.. code-block:: rst
+
+  Title of File (using title case)
+  =================================
+
+  Introduction text.
+
+  Section Title
+  -------------
+
+  We use double backticks to indicate ``inline-code`` including file names, function and method names, paths, etc.
+
+  Longer code-blocks should begin with the ``.. code-block:: [type]`` directive and should be indented at least one
+  level. There should also be a blank line before and after it as shown below.
+
+  .. code-block:: sql
+    if ($needs_documentation) {
+        use $these_guidelines;
+        $contribute_docs = $appreciated;
+    }
+
+  Section 1.1 Title
+  ^^^^^^^^^^^^^^^^^
+
+  The use of appropriate sections makes reading documentation and later specific details easier. Sub sections such
+  as this one will be hidden unless the main section is already selected.
+  ```

docs/dev_guide/contributing/governance.rst

@@ -0,0 +1,19 @@
+Tripal Governance
+==================
+
+Changes to this Document
+--------------------------
+
+
+These guidelines are binding to the Tripal Community. If you have comments or questions, please `comment on the Github issue <https://github.com/tripal/tripal/issues/344>`_. Changes to this document will be made after adequate discussion has occurred and the project management committee has voted in favor of the change.
+
+Governance Structure
+---------------------
+
+The Tripal project recognizes these roles:
+
+- Users: They have downloaded Tripal!  Maybe they even have a site!
+- Contributors: contributing!  Code, comments, discussion, questions, bug reports.
+- Committers: write access to the repository.
+- PMC: Makes **code relevant** decisions.
+- Oversight committee: Makes **policy level** decisions.  This may overlap with PMC, but the idea is the oversight committee includes parties who are **not necessarily coders** and therefore not reviewing Pull requests etc.

docs/dev_guide/contributing/pull_requests.rst

@@ -0,0 +1,130 @@
+Guidelines for Contribution to Tripal
+========================================
+
+The following guidelines are meant to encourage contribution to Tripal source-code on GitHub by making the process open, transparent and collaborative. If you have any feedback including suggestions for improvement or constructive criticism, please `comment on the Github issue <https://github.com/tripal/tripal/issues/344>`_. **These guidelines apply to everyone contributing to Tripal whether it's your first time (Welcome!) or project management committee members.**
+
+.. note::
+
+  These guidelines are specifically for contributing to `Tripal <https://github.com/tripal/tripal>`_. However, we encourage all Tripal extension modules to consider following these guidelines to foster collaboration among the greater Tripal Community.
+
+.. note::
+
+	Guidelines serve as suggestions ( **should** ) or requirements (**must**). When the word "should" is used in the text below, the stated policy is expected but there may be minor exceptions.  When the word "must" is used there are no exceptions to the stated policy.
+
+
+Github Communication Tips
+---------------------------
+
+- Don't be afraid to mention people (@username) who are knowledgeable on the topic or invested.  *We are academics and overcommitted, it's too easy for issues to go unanswered: don't give up on us!*
+- Likewise, don't be shy about bumping an issue if no one responds after a few days. *Balancing responsibilities is hard.*
+- Want to get more involved? Issues marked with "Good beginner issue" are a good place to start if you want to try your hand at submitting a PR.
+- Everyone is encouraged/welcome to comment on the issue queue! Tell us if you
+    - are experiencing the same problem
+    - have tried a suggested fix
+    - know of a potential solution or work-around
+    - have an opinion, idea or feedback of any kind!
+- Be kind when interacting with others on Github! (see Code of Conduct below for further guidelines). We want to foster a welcoming, inclusive community!
+    - Constructive criticism is welcome and encouraged but should be worded such that it is helpful :-) Direct criticism towards the idea or solution rather than the person and focus on alternatives or improvements.
+
+Bugs
+-----
+
+
+- Every bug **should** be reported as a Github issue.
+    - Even if a bug is found by a committer who intends to fix it themselves immediately, they **should** create an issue and assign it to themselves to show their intent.
+- Please follow the issue templates as best you can.  This information makes discussion easier and helps us resolve the problem faster.
+    - Also provide as much information as possible :-)  Screenshots or links to the issue on a development site can go a long way!
+- Bonus points for unit tests to ensure the bug does not return :-)
+
+Feature Requests
+------------------
+
+- Every feature request should start as an issue so that discussion is encouraged :-)
+- Please provide the following information (bold is required; underlined strengthens your argument):
+    - **Use Case:** fully describe why you need/want this feature
+    - Generally Applicable: Why do you feel this is generally applicable? Suggest other use cases if possible. Mention (@) others that might want/need this feature.
+    - Implementation: Describe a possible implementation. Bonus points for configuration, use of ontologies, ease of use, permission control, security considerations
+- All features **should** be optional so that Tripal admin can choose to make it available to their users.
+    - When applicable, new features should be designed such that Tripal-site admin can disable them.
+    - Bonus points: for making new features configurable and easily themed.
+- Feature requests will be voted on by the project management and advisory/steering committees to determine if it should be included in core, an existing extension module or it's own extension module.
+    - Votes should be based on whether this feature is generally applicable and doesn't exclude existing users and not be biased by the needs of your own Tripal site.
+- If a feature isn't suitable for inclusion within Tripal core, use the issue discussion as a springboard to create a Tripal extension module!
+
+.. note::
+
+  In the future there will be a set of guidelines for what should be included in core. This will make the process of requesting new features more streamlined, inclusive and transparent.
+
+Pull Request (PR) Guideline
+----------------------------
+
+The goal of this document is to make it easy for **A)** contributors to make pull requests that will be accepted, and **B)** Tripal committers to determine if a pull request should be accepted.
+
+- PRs that address a specific issue **must** link to the related issue page.
+    - Really in almost every case, there should be an issue for a PR.  This allows feedback and discussion before the coding happens.  Not grounds to reject, but encourage users to create issues at start of their PR.  Better late than never :).
+- Each PR **must** be tested/approved by at least 2 users with at least one user being a "trusted committer."
+    - Testers **should** describe how the testing was performed if applicable (allows others to replicate the test).
+    - At the Project Management Committee's (PMC) discretion, a PR may be subject to only one review.  Generally these are small and obvious commits.
+    - While Tripal's review body is small, only one of the code reviews must be a thorough functional test.
+    - Tripal's guiding philosophy is to encourage open contribution.  With this in mind, committers should **work with contributors** to resolve issues in their PRs.  PRs that will not be merged should be closed, **transparently citing** the reason for closure.  In an ideal world, features that would be closed are discouraged at the **issue phase** before the code is written!
+    - The pull request branch should be deleted after merging (if not from a forked repository) by the person who performs the merge.
+- PRs that include new functionality **must** also provide Unit Tests.
+    - Tests **must** test the new functionality added.
+    - Bonus points for testing all surrounding functionality.
+    - For example, when adding feature X to custom tables, the PR must include tests for feature X and we would be greatly appreciative if it included tests for custom tables in general :-D.
+- PRs **should** pass all Travis-CI tests before they are merged.
+- Branches **should** follow the following format:
+    - ``[issue\_number]-[tripal\_version]-[short\_description]``
+    - ``tripal\_version`` being Tv2, Tv3, etc.
+    - ``-[short\_description]`` being optional but highly encouraged
+- **Must** follow `Drupal code standards <https://www.drupal.org/docs/develop/standards>`_
+- PRs for new feature should remain open until adequately discussed (see guidelines below) and approved by a vote (all members of the PMC must vote in favour).
+
+
+.. note::
+
+  If you need more instructions creating a pull request, see for example the `KnowPulse workflow <https://knowpulse.readthedocs.io/en/latest/developer_docs/dev_workflow.html#workflow>`_
+
+How PRs and Issues are Handled
+------------------------------
+The Project Management Committee (PMC) and trusted committers will follow specific rules when working with all issues and pull requests. The rules are listed below. Anyone may provide bug fixes in which case some of the following will apply to all:
+
+- **Every task related to Tripal (bug, feature requests, documentation, discussions) should be in Github, either as it's own issue or grouped with like tasks into a single issue.** This effectively puts our todo list on github making it transparent to anyone who wants to help. It has the benefit of showing how active our community is, keeps everyone informed with where Tripal is headed and makes it easy for others to chime in with experience, comments and support.
+- **Guidelines for Tagging Issues:**
+    - The first committer who comments on an issue should tag it with the version of Tripal it applies to.
+    - Issues with a suggested fix or work-around should be tagged with "Fix Required" to let others know a PR is needed.
+    - Only tag an issue with "bug" once it has been shown to be reproducible. If it's not reproducible by a committer but you feel it is a bug then tag it as "potential bug".
+    - If multiple users have commented that a bug affects them, tag it as "affects multiple users".
+    - Issues that require a PR and someone with relatively little Tripal experience could fix should be tagged with "Good beginner issue"
+    - All feature requests should be tagged as an "enhancement"
+    - If you are the first reviewer to confirm a PR works, tag it with "Reviewer #1 Approval"
+- **Guidelines for Discussion:**
+    - Issues that do not require discussion (PRs still require 2 reviews): minor bug fixes, changes to inline comments, addition of unit tests, minor code typos
+    - Issues that require discussion: major changes, new features, and issue at the discretion of the PMC
+      - Add the "discussion" tag to any issue requiring discussion
+      - Discussion Tag is removed when adequate discussion has taken place (at the discretion of the person who added the tag)
+      - Additionally, new features require that all members of the PMC have had a chance to contribute to the discussion and feel satisfied.
+- Please use the **assignment** feature to clarify who will be contributing the code to prevent duplication of effort.
+    - When assigning yourself, comment on what your timeline is. This allows others to jump in if they have time sooner.
+    - If you would like to **take over a PR assigned to someone else** , comment asking for an update and offer your services.
+    - If the author of the issue plans on contributing the fix themselves but is not a committer, they should indicate that in the issue.  A committer will assign them the issue.
+- When you start working on an issue, you **should** create the branch and push to it regularly. If you are working on a fork, you're **encouraged** to link to it in the issue.
+    - Committers can work on a fork or directly.  If the branch is on tripal/tripal, then other committers should contribute via PR unless otherwise agreed
+- If an issue is identified as being relevant to another repository (ie a tripal module, not core), a new issue **should** be created, cross referenced, and the original issue should be closed encouraging discussion in the module.
+
+Code of Conduct
+----------------
+
+
+- Be nice!  If that's insufficient, Tripal community defers to https://www.contributor-covenant.org/
+
+Testing/CI
+------------
+
+
+Comprehensive guides to testing are available in the :ref:`tests` section.  Below are guiding principles.
+
+- All tests pass.
+- Tests don't modify db: use transactions and factories.
+- Tests are organized properly: by submodule and function.
+- Tests run quietly.

docs/dev_guide/contributing/tests.rst

@@ -0,0 +1,188 @@
+.. _tests:
+
+Unit Tests for Tripal
+=======================
+
+This guide is for developers looking to contribute code to the core Tripal project.  It introduces the testing philosophy and guidelines for Tripal core.  Tripal uses Tripal Test Suite, which brings bootstraps your Tripal site for PHPUnit.  It also provides conveniences like name spacing, seeders, transactions, and data factories.
+
+Tripal Test Suite
+-------------------
+
+For a basic introduction of Tripal Testing, please see the `Test Suite documentation <https://tripaltestsuite.readthedocs.io/en/latest/>`_.
+
+Installation
+~~~~~~~~~~~~~~
+
+After cloning the `Tripal Github repo <https://github.com/tripal/tripal>`_, you will need to install the developer dependencies required to run tests locally.  To do this, you'll need to `install Composer <https://getcomposer.org/doc/00-intro.md>`_, and then execute ``composer install`` in your project root.
+
+Remember to run ``composer update`` to update Tripal TestSuite before writing and running new tests. This is especially important when running pull requests that contribute unit tests. If tests are passing on the Travis environment but not on your machine, running composer update might resolve the problem.
+
+Testing criteria
+-----------------
+
+For facilitate accepting your pull requests, your code should include tests.  The tests should meet the following guidelines:
+
+* All tests pass
+* Tests pass in all environments (Travis)
+* Tests don't modify the database (use transactions or clean up after yourself)
+* Tests are properly organized (see organization section below)
+* Tests run quietly
+
+Test organization
+------------------
+
+Tests should be placed in ``tests/``.  This root directory contains the following files:
+ - ``bootstrap.php``: Test directory configuration.  Don't modify this.
+ - ``DatabasSeeders/``: `Database seeders <https://github.com/statonlab/TripalTestSuite#database-seeders>`_, for filling Chado with permanent test data.
+ - ``DataFactory.php``: `Data factories <https://github.com/statonlab/TripalTestSuite#factories>`_, for providing test-by-test Chado data.
+ - ``example.env``: An example environment file.  Configure this to match your development site and save as ``.env``.  Read more here: https://tripaltestsuite.readthedocs.io/en/latest/environment.html
+
+Test files must end with ``Test.php`` to be recognized by PHPUnit.  The tests themselves should be organized by submodule, and category.
+
+Submodules
+~~~~~~~~~~~
+
+* tripal
+* tripal_bulk_loader
+* tripal_chado
+* tripal_chado_views
+* tripal_daemon
+* tripal_ds
+* tripal_ws
+
+Categories
+~~~~~~~~~~
+
+* API
+* theme
+* views
+* drush
+* fields
+* entities
+* admin
+* loaders
+
+So for example, tests for the file ``tripal/api/tripal.jobs.api.inc`` should go in ``tests/tripal/api/TripalJobsAPITest.php``. tests that don't fit in any of these categories should be placed in ``tests/[submodule]/``.
+
+In order for tests to run locally, you'll need an environmental file ``tests/.env`` with the project root, base url, and locale.  See ``tests/example.env`` for an example.
+
+Writing tests
+--------------
+
+Tagging tests
+~~~~~~~~~~~~~~~~
+
+You should tag your test with relevant groups.  For example, our Tripal Chado API tests should be tagged with ``@group api``.  We don't need to tag it with ``@group chado`` because it is in the *testsuite* (the submodule folder) Chado.
+
+If your test is related to a specific issue on the Tripal repo, thats great! You can use the ``@ticket`` tag to link it: ie, ``@ticket 742`` for issue number 742.
+
+Defining the test class
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The test class file should extend ``StatonLab\TripalTestSuite\TripalTestCase`` instead of ``TestCase`` to take advantage of the Tripal Test Suite tools.  Tests should use a database transaction to ensure the database state is the same at the start and end of the test case.  Your test class name should match the file.
+
+
+.. code-block:: php
+
+  use StatonLab\TripalTestSuite\DBTransaction;
+  use StatonLab\TripalTestSuite\TripalTestCase;
+
+  class TripalChadoOrganismAPITest extends TripalTestCase {
+  	use DBTransaction;
+  }
+
+
+Defining individual tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An ideal test operates *independently* of other tests: by default, unit tests run in random order.  How, then, do we provide our test with relevant data?  We use **Factories**, which you can read about on in the `Tripal Test Suite documentation <https://tripaltestsuite.readthedocs.io/en/latest/factories.html>`_.  In the below example, we create an organism with known information, and assert that we can retrieve it with the Chado API functions.
+
+
+.. code-block:: php
+
+
+  namespace Tests\tripal_chado\api;
+
+  use StatonLab\TripalTestSuite\DBTransaction;
+  use StatonLab\TripalTestSuite\TripalTestCase;
+
+  class TripalChadoOrganismAPITest extends TripalTestCase {
+
+    use DBTransaction;
+
+    /**
+     * Test tripal_get_organism.
+     *
+     * @group api
+     */
+    public function test_tripal_get_organism() {
+
+      $genus_string = 'a_genius_genus';
+      $species_string = 'fake_species';
+
+      $organism = factory('chado.organism')->create([
+        'genus' => $genus_string,
+        'species' => $species_string,
+      ]);
+
+      $results = [];
+
+      $results[] = tripal_get_organism(['organism_id' => $organism->organism_id]);
+      $results[] = tripal_get_organism([
+        'genus' => $genus_string,
+        'species' => $species_string,
+      ]);
+
+      foreach ($results as $result) {
+        $this->assertNotFalse($result);
+        $this->assertNotNull($result);
+        $this->assertObjectHasAttribute('genus', $result);
+        $this->assertEquals($genus_string, $result->genus);
+      }
+    }
+
+    public function test_tripal_get_organism_fails_gracefully() {
+      $result = tripal_get_organism([
+        'genus' => uniqid(),
+        'species' => uniqid(),
+      ]);
+
+      $this->assertNull($result);
+    }
+  }
+
+
+.. note::
+
+  You typically will want at least one test per public method in your file or class. Tests should start with ``test_``, otherwise it wont run by default in PHPUnit (you can also declare that it is a test in the method documentation using ``@test``.
+
+Testing quietly
+~~~~~~~~~~~~~~~~
+
+Tests should run quietly.  If the output goes to standard out, you can use ``ob_start()`` and ``ob_end_clean()``.
+
+
+.. code-block:: php
+
+
+    ob_start();//dont display the job message
+    $bool = tripal_chado_publish_records($values);
+    ob_end_clean();
+
+
+If the message comes from the Tripal error reporter, you must use ``"TRIPAL_SUPPRESS_ERRORS=TRUE"`` to suppress the Tripal error reporter message.
+
+.. code-block:: php
+
+
+  /**
+   * Test chado_publish_records returns false given bad bundle.
+   *
+   * @group api
+   */
+  public function test_tripal_chado_publish_records_false_with_bad_bundle() {
+    putenv("TRIPAL_SUPPRESS_ERRORS=TRUE");//this will fail, so we suppress the tripal error reporter
+    $bool = tripal_chado_publish_records(['bundle_name' => 'never_in_a_million_years']);
+    $this->assertFalse($bool);
+    putenv("TRIPAL_SUPPRESS_ERRORS");//unset
+  }

tests/README.md

@@ -1,175 +1 @@
-
-This guide is for developers looking to contribute code to the core Tripal project.  It introduces the testing philosophy and guidelines for Tripal core.  Tripal uses Tripal Test Suite, which brings bootstraps your Tripal site for PHPUnit.  It also provides conveniences like namespacing, seeders, transactions, and data factories.
-
-
-## Tripal Test Suite
-
-For a basic introduction of Tripal Testing, please see the [Test Suite repo](https://github.com/statonlab/TripalTestSuite).
-
-
-### Installation
-
-After cloning the [Tripal github repo](https://github.com/tripal/tripal), you will need to install the developer dependencies required to run tests locally.  To do this, you'll need to [install Composer](https://getcomposer.org/doc/00-intro.md), and then execute `composer install` in your project root.
-
-Remember to run `composer update` to update TripalTestSuite before writing and running new tests. This is especially important when running pull requests that contribute unit tests. If tests are passing on the Travis environment but not on your machine, running composer update might resolve the problem.
-
-## Testing criteria
-For facilitate accepting your pull requests, your code should include tests.  The tests should meet the following guidelines:
-
-* All tests pass
-* Tests pass in all environments (Travis)
-* Tests don't modify the database (use transactions or clean up after yourself)
-* Tests are properly organized (see organization section below)
-* Tests run quietly
-
-## Test organization
-
-Tests should be placed in `tests/`.  This root directory contains the following files:
-* `bootstrap.php` - Test directory configuration.  Don't modify this.
-* `DatabasSeeders/` - [Database seeders](https://github.com/statonlab/TripalTestSuite#database-seeders), for filling Chado with permanent test data
-* `DataFactory.php` - [Data factories](https://github.com/statonlab/TripalTestSuite#factories), for providing test-by-test Chado data.
-* `example.env` - An example environment file.  Configure this to match your development site and save as `.env`.
-
-Tests must end with `Test.php` to be recognized by PHPUnit.  The tests themselves should be organized by submodule, and category.  
-
-##### Submodules
-
-* tripal
-* tripal_bulk_loader
-* tripal_chado
-* tripal_chado_views
-* tripal_daemon
-* tripal_ds
-* tripal_ws
-
-##### Categories
-* API
-* theme
-* views
-* drush
-* fields
-* entities
-* admin
-* loaders
-
-So for example, tests for the file `tripal/api/tripal.jobs.api.inc` should go in `tests/tripal/api/TripalJobsAPITest.php`. tests that don't fit in any of these categories should be placed in `tests/[submodule]/`.
-
-In order for tests to run locally, you'll need an environmental file `tests/.env` with the project root, base url, and locale.  See `tests/example.env` for an example.
-
-## Writing tests
-
-When doing test driven development, you might be running tests over and over.  To speed you along, you can assign your tests a unique `@group` tag, ie `@group failing`.  Then specify your novel group when you run phpunit, ie `phpunit --group failing`.
-
-You should also tag your test with relevant groups.  For example, our Tripal Chado API tests should be tagged with `@group api`.  We don't tag it with `@group chado` because it is in the *testsuite* (the submodule folder) Chado.
-
-
-## Defining the test class
-
-
-Once you've identified where your test will go, we can start writing our test.
-
-
-Tripal Test suite provides a convenient way to start writing a test class: `tripaltest make:test TestName`.  From the project root, our example  `./vendor/bin/tripaltest make:test tripal_chado/api/TripalChadoOrganismAPITest`.  This will generate a test stub file with namespacing.
-
-
-The test class file should extend `StatonLab\TripalTestSuite\TripalTestCase` instead of `TestCase` to take advantage of the Tripal Test Suite tools.  For example, to wrap our tests in a database transaction (so we can indescriminately insert and modify without having to revert consider how to clean up the database after), we use `StatonLab\TripalTestSuite\DBTransaction;`.  Your test class name should match the file.
-
-
-```php
-use StatonLab\TripalTestSuite\DBTransaction;
-use StatonLab\TripalTestSuite\TripalTestCase;
-
-class TripalChadoOrganismAPITest extends TripalTestCase {
-	use DBTransaction;
-
-```
-
-
-You typically will want at least one test per public method in your file or class. In the below test class, I define a single test: `test_tripal_get_organism()`.  The test should start with `test_`, otherwise it wont run by default in PHPUnit (you can also declare that it is a test in the method documentation using `@test`.   
-
-An ideal test operates *independently* of other tests: by default, unit tests run in random order.  How, then, do we provide our test with relevant data?  We use **Factories**, which you can read about on the [Tripal Test Suite repo](https://github.com/statonlab/TripalTestSuite#factories).  In the below example, we create an organism with known information, and assert that we can retrieve it with the Chado API functions.
-
-
-
-```php
-
-namespace Tests\tripal_chado\api;
-
-use StatonLab\TripalTestSuite\DBTransaction;
-use StatonLab\TripalTestSuite\TripalTestCase;
-
-class TripalChadoOrganismAPITest extends TripalTestCase {
-
-  use DBTransaction;
-
-  /**
-   * Test tripal_get_organism.
-   *
-   * @group api
-   */
-  public function test_tripal_get_organism() {
-
-    $genus_string = 'a_genius_genus';
-    $species_string = 'fake_species';
-
-    $organism = factory('chado.organism')->create([
-      'genus' => $genus_string,
-      'species' => $species_string,
-    ]);
-
-    $results = [];
-
-    $results[] = tripal_get_organism(['organism_id' => $organism->organism_id]);
-    $results[] = tripal_get_organism([
-      'genus' => $genus_string,
-      'species' => $species_string,
-    ]);
-
-    foreach ($results as $result) {
-      $this->assertNotFalse($result);
-      $this->assertNotNull($result);
-      $this->assertObjectHasAttribute('genus', $result);
-      $this->assertEquals($genus_string, $result->genus);
-    }
-  }
-
-  public function test_tripal_get_organism_fails_gracefully() {
-    $result = tripal_get_organism([
-      'genus' => uniqid(),
-      'species' => uniqid(),
-    ]);
-
-    $this->assertNull($result);
-  }
-
-```
-### Testing quietly
-
-Code may output errors when failing intentionally, or as part of job progress.  This can clutter the test environment, so you should wrap the offending methods.  If the output goes to standard out, you can use `ob_start()` and `ob_end_clean()`.
-
-
-```php
-
-    ob_start();//dont display the job message
-    $bool = tripal_chado_publish_records($values);
-    ob_end_clean();
-
-```
-
-If the message comes from the Tripal error reporter, you must use `"TRIPAL_SUPPRESS_ERRORS=TRUE"` to suppress the tripal error reporter message.
-
-```php
-
-  /**
-   * Test chado_publish_records returns false given bad bundle.
-   *
-   * @group api
-   */
-  public function test_tripal_chado_publish_records_false_with_bad_bundle() {
-    putenv("TRIPAL_SUPPRESS_ERRORS=TRUE");//this will fail, so we suppress the tripal error reporter
-    $bool = tripal_chado_publish_records(['bundle_name' => 'never_in_a_million_years']);
-    $this->assertFalse($bool);
-    putenv("TRIPAL_SUPPRESS_ERRORS");//unset
-  }
-
- ```
+Please see the [Tripal online documentation](https://tripal.readthedocs.io/en/latest/dev_guide/contributing.html) for instructions on how to set up the Tripal Test environment and testing standards.