From a555817d6fd42f56f955d8ebf227f171f132a2cd Mon Sep 17 00:00:00 2001 From: Cam Findlay Date: Mon, 19 Oct 2015 11:44:31 +1300 Subject: [PATCH] DOCS Module standard 1.0 Adding the module standard to 3.2+ docs. --- .../05_Extending/00_Modules.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/en/02_Developer_Guides/05_Extending/00_Modules.md b/docs/en/02_Developer_Guides/05_Extending/00_Modules.md index 62478a282..75f955dbd 100644 --- a/docs/en/02_Developer_Guides/05_Extending/00_Modules.md +++ b/docs/en/02_Developer_Guides/05_Extending/00_Modules.md @@ -101,6 +101,51 @@ operate in other structures, paths to static files such as CSS or JavaScript won See the [How to Publish a SilverStripe Module](how_tos/publish_a_module) for details on how to publish your SilverStripe modules with the community +## Module Standard + +The SilverStripe module standard defines a set of conventions that high-quality SilverStripe modules should follow. It’s a bit like PSR for SilverStripe CMS. Suggested improvements can be raised as pull requests. + +### Coding Guidelines + + * Declaration of level of support is provided for each module (either via README.md or composer) including the below. + * Level of support provided. + * Supporting user(s) and/or organisation(s). + * Complies to a well defined module directory structure and coding standards: + * templates (for ss templates) + * code (for php files) + * tests (for php test files) and + * _config (for yml config) + * The module is a Composer package. + * All Composer dependencies are bound to a single major release (e.g. ^3.1 not >=3.1). + * There is a level of test coverage. + * A clear public API documented in the docblock tags. + * Recommend the use of [PSR-1](http://www.php-fig.org/psr/psr-1/) and [PSR-2](http://www.php-fig.org/psr/psr-2/). + * .gitattributes will be used to exclude non-essential files from the distribution. At a minimum tests, docs, and IDE/dev-tool config should be excluded. + +### Documentation Guidelines + +Documentation will use the following format: + + * README.md provides: + * Links or badges to CI and code quality tools. + * A short summary of the module, end-user. + * Installation instructions + * Testing/development instructions and a link to contrib instructions. + * How to report security vulnerabilities. Note that PSR-9 / PSR-10 may be recommended once released. + * Security, license, links to more detailed docs. + * CONTRIBUTING.md explaining terms of contribution. + * A changelog CHANGELOG.md (may link to other more detailed docs or GitHub releases if you want). + * Has a licence (LICENSE.md file) - for SilverStripe supported this needs to be BSD. + * Detailed documentation in /docs/en as a nested set of GitHub-compatible Markdown files. + * Links and image references are relative, and are able to be followed in viewers such as GitHub. + * Markdown may include non-visible comments or meta-data. + +Documentation will cover: + + * Installation + * Configuration + * Usage guides for key features; screenshots are recommended. + * A committers guide, covering PR-merging and release guidelines. ## Related