Issue #2747309 by Mile23: Add CONTRIBUTING.md, STANDARDS.md, TESTING.md for contributors

Author: Mile23

CONTRIBUTING.md

@@ -0,0 +1,63 @@
+Drupal Examples For Developers: Contributor's Guide
+===================================================
+
+Examples for Developers is a community project.
+
+If you'd like to participate in Examples development, thank you!
+
+If you are new to Drupal or open source in general, have no fear. Examples is
+an easy-going project where you can learn some things about how to work on a
+collaborative project in a friendly environment.
+
+
+Policies
+--------
+
+Examples follows the Drupal core process as much as possible.
+
+Contributions thus need to be similar in quality to Drupal core patches.
+Contributions will need to meet the following minimum standards:
+
+### Normal Drupal issue process
+
+Drupal projects use patches related to issues. You should know how to make a
+patch and an interdiff using git. It's fine to develop on github or
+what-have-you, but eventually it has to be a patch that can be reviewed in the
+normal Drupal issue process. See the list of resources for some information on
+how to do do this.
+
+Your patch will also need to be reviewed by someone other than yourself. Learn
+about the review process in the resources section.
+
+### DrupalCI
+
+Examples uses the Drupal automated testing system to verify the applicability of
+patches. See `TESTING.md` for details.
+
+### Drupal coding standards
+
+All code in Examples should adhere to the Drupal core coding standards. Examples
+uses the Drupal Coder project and PHP_CodeSniffer to enforce coding standards.
+Think of this as another test your code must pass. See `STANDARDS.md` for
+details.
+
+
+Resources
+---------
+
+### Novice
+
+Drupal novice contribution guide: https://www.drupal.org/novice
+
+Drupal contribution guide: https://www.drupal.org/contribute
+
+What's a patch? https://www.drupal.org/patch
+
+How to make a patch with git: https://www.drupal.org/node/707484
+
+### Everyone
+
+How to review a patch: https://www.drupal.org/patch/review
+
+See `STANDARDS.md` and `TESTING.md` for information on how to run a coding
+standards test, and also how to run the tests themselves.

STANDARDS.md

@@ -0,0 +1,61 @@
+HOWTO: Drupal Examples For Developers Coding Standards
+=======================================================
+
+Examples uses the same coding standards as Drupal core.
+
+Examples has a `phpcs.xml.dist` file at the root of the project. This file
+specifies the current coding standards 'sniffs' which code in the project must
+pass.
+
+The `phpcs.xml.dist` file is used by a tool called PHP_CodeSniffer (`phpcs`).
+
+Contributors should install `phpcs` in their local Drupal installation, and then
+use that to run `phpcs` against Examples as part of their development and review
+process.
+
+Contributors can also patch the `phpcs.xml.dist` file itself, in order to fix
+the codebase to pass a given rule or sniff. Patches which do this should be
+limited to a single rule or sniff, in order make the patch easier to review.
+
+Installing phpcs
+----------------
+
+Generally: Use Composer to add Drupal's Coder project to your root
+Drupal project. Coder contains the PHP_CodeSniffer rules we need, and
+also requires `phpcs`.
+
+Then tell `phpcs' where our Drupal-specific rules are.
+
+Like this:
+
+  $ cd my/drupal/root/
+  $ composer require drupal/coder
+  // Composer installs Coder, which requires PHP_CodeSniffer as well.
+  // Configure phpcs to use the Drupal standard rules...
+  $ ./vendor/bin/phpcs --config-set installed_paths /path/to/drupal/vendor/drupal/coder/coder_sniffer/
+  // phpcs now knows how to find the Drupal standard. You can test it:
+  $ cd core
+  $ ../vendor/bin/phpcs -e --standard=Drupal
+  // Shows you a bunch of Drupal-related sniffs.
+
+Running phpcs
+-------------
+
+Now you can run phpcs:
+
+  $ cd modules/examples
+  $ ../../vendor/bin/phpcs -p -s
+  // phpcs uses Exampes' phpcs.xml.dist to verify coding standards.
+  // -p shows you progress dots.
+  // -s shows you sniff errors in the report.
+
+If there are errors, they can sometimes be fixed with `phpcbf`, which is
+part of the `phpcs` package.
+
+  $ ../../vendor/bin/phpcbf
+  // phpcbf now performs automated fixes.
+
+Always look at the changes to see what `phpcbf` did.
+
+And always re-run `phpcs` in order to discover whether `phpcbf` handled all the
+errors.

TESTING.md

@@ -0,0 +1,48 @@
+Testing Drupal Examples for Developers
+======================================
+
+The Drupal Examples for Developers project uses DrupalCI testing on drupal.org.
+
+That means: It runs the testbot on every patch that is marked as 'Needs Review.'
+
+Your patch might not get reviewed, and certainly won't get committed unless it
+passes the testbot.
+
+The testbot runs a script that's in your Drupal installation called
+`core/scripts/run-tests.sh`. You can run `run-tests.sh` manually and approximate
+the testbot's behavior.
+
+You can find information on how to run `run-tests.sh` locally here:
+https://www.drupal.org/node/645286
+
+You should at least run `run-tests.sh` locally against all the changes in your
+patch before uploading it.
+
+Keep in mind that unless you know you're changing behavior that is being tested
+for, the tests are not at fault. :-)
+
+Note also that, currently, using the `phpunit` tool under Drupal 8 will not find
+PHPUnit-based tests in submodules, such as phpunit_example. There is no
+suggested workaround for this, since there is no best practice to demonstrate as
+an example. There is, however, this issue in core:
+https://www.drupal.org/node/2499239
+
+
+What Tests Should An Example Project Have?
+------------------------------------------
+
+Examples has a checklist for each module:
+https://www.drupal.org/node/2209627
+
+The reason we care about these tests is that we want the documentation
+of these APIs to be correct. If Core changes APIs, we want our tests to
+fail so that we know our documentation is incorrect.
+
+Our list of required tests includes:
+* Functional tests which verifies a 200 result for each route/path defined by
+    the module.
+* Functional tests of permission-based restrictions.
+* Functional tests which submit forms and verify that they behave as
+    expected.
+* Unit tests of unit-testable code.
+* Other. More. Better.