README

This module provides a check suite, and a set of automated checks that can be run over a SilverStripe module to determine a "quality rating".

This library can be installed into a SilverStripe 3 or 4 project that uses Composer.

Installation

You can install this library with Composer if you want to use its public API:

composer require silverstripe/moduleratings

You can also install the silverstripe/moduleratings-plugin Composer plugin, which will provide a Composer command you can run locally to check module quality ratings. Please see the readme in that module for more information on using it.

Requirements

• symfony/finder 3 or 4
• symfony/yaml 3 or 4

Note: If you have conflicts with any of the symfony components (if using the Composer plugin) during installation, you may need to manually require an older version of one or both of those packages, e.g.:

composer require symfony/yaml ~3.0
composer require symfony/console ~3.0

Using the API

To create a check suite, use the SilverStripe\ModuleRatings\CheckSuite class. You will need to provide the directory path to the module code you want to check, and optionally the GitHub repository slug for the module (note: only GitHub supported at this stage). Providing the repository slug will enable checks that look at external continuous integration system APIs to determine quality metrics (e.g. Travis, Scrutinizer).

$checkSuite = new \SilverStripe\ModuleRatings\CheckSuite();

$checkSuite
    ->setModuleRoot('/path/to/silverstripe/framework')
    ->setRepositorySlug('silverstripe/silverstripe-framework');

$checkSuite->run();

echo 'Framework has scored ' . $checkSuite->getScore() . ' out of 100 points. Details:', PHP_EOL;
print_r($checkSuite->getCheckDetails());

The return data from CheckSuite::getCheckDetails is an array with the following example structure (note that example is JSON encoded):

{
  "good_code_coverage": {
    "description": "Has a \"good\" level of code coverage (greater than 40%, requires slug)",
    "points": 5,
    "maximum": 5
  },
  "has_code_of_conduct_file": {
    "description": "Has a code of conduct file",
    "points": 2,
    "maximum": 2
  },
  "coding_standards": {
    "description": "The PHP code in this module passes the SilverStripe lint rules (mostly PSR-2)",
    "points": 0,
    "maximum": 10
  }
 }

Available checks

• "Good" code coverage (>= 40%) (via either Scrutinizer CI or Codecov.io)
• "Great" code coverage (>= 75%) (via either Scrutinizer CI or Codecov.io)
• PHP code is in either "code" or "src" folder
• PHP code passes a PSR-2-ish linting standards check (phpcs.xml.dist is stored in src/Check/CodingStandardCheck for reference)
• Contributing guide file exists
• Has documentation
• EditorConfig configuration file exists
• .gitattributes file exists
• A license file exists
• The repository has a readme
• Scrutinizer CI is configured and has a "good" quality rating (>= 6.5/10)
• One of either Travis CI or CircleCI is configured and the last build passed successfully

The registered checks are defined in config.yml along with the number of points awarded for each check given that it passes.

Caveats

Please note the following caveats/gotchas/todos:

• Code repositories must exist on GitHub for external API checks to work

Thanks!

A huge thank you to Chris Pitt who originally wrote Helpful Robot, the inspiration for this library.

The checks in this library are heavily inspired by the original Helpful Robot checks, and are designed to match the SilverStripe commercially supported module standard.

Without Helpful Robot the SilverStripe community would look a lot less tidy today!