Supported Modules Definition
Supported by an active open source community, Silverstripe modules extend Silverstripe CMS, providing additional functionality such as blogging, user customisable forms, workflow, and lots more.
Supported Modules take this one step further. By having the backing of Silverstripe Ltd, there is a dedicated team of developers actively maintaining Silverstripe Supported Modules.
As well as having the advantages of being open source, community projects, Supported Modules have:
- Compatibility with the latest Silverstripe CMS stable release
- Security patches applied immediately
- Major bugs squashed quickly
- High level of testing to ensure quality
- User and technical documentation
By using Supported Modules, agencies and developers can build projects with confidence, knowing these modules have been tested and have the backing of Silverstripe Ltd.
Developers are encouraged to use Community Supported Modules alongside Silverstripe Supported Modules. Many of these modules are very high quality and provide functionality not available in the Silverstripe Supported Modules sub-set.
Module Standard 1.0
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.
The Module Standard is part of the Silverstripe Framework docs and thereby hosted on docs.silverstripe.org. 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 and 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
- A changelog CHANGELOG.md (may link to other more detailed docs 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.
- It is suggested to use a documentation page named
userguide.md
indocs/en/
that includes documentation of module features that have CMS user functionality (if applicable). For modules with large userguides, this should be in a directory nameduserguide
with anindex.md
linking to any other userguide pages. - Links and image references are relative, and are able to be followed in viewers such as GitHub.
- Page Metadata can be added to pages.
Documentation will cover:
- Installation
- Configuration
- Usage guides for key features; screenshots are recommended.
- A committers guide, covering PR-merging and release guidelines.
Supporting Tools
The following supporting tools will be configured and maintained:
- Public source code (GitHub)
- Issue tracking (GitHub)
- Feature requests (UserVoice/GitHub)
- CI testing (Travis)
- Code quality testing (Scrutinizer)
Module scores on addons.silverstripe.org
The Silverstripe CMS catalogue of modules contains a simple scoring indicator on some of the more objective aspects of the Module Standard. We make use of a scoring API that analyses Silverstripe modules and provides a set of weighted scores.
This gives module maintainers an indication of where targeted improvements could be made and, for developers selecting modules, a way to make an informed decision.
Score indicators
|
Green is meeting 70+% of the standard as measured by the API. |
|
Half green represents the module scores above the overall community average score and below 70%. |
Grey indicates the module scores below community average score. |
An example of a score indicator looks like this:
Module score weightings
An example of a breakdown of scoring details for a module looks like this:
This would indicate that, to gain further score, the maintainer could add a "contributing.md" file explaining how they would like to accept contributions to the module or any other aspects indicated as not present.
Silverstripe Commercial Module Support
In addition to adhering to the Module Standard, the modules supported by Silverstripe Ltd will do the following
Maintenance Expectations
Team:
- We recommend at least 3 committers with the permission to merge pull requests, manage issues, and produce a stable releases.
Communication:
- Issues & pull requests are responded to within a reasonable timeframe.
- For unacceptable pull requests, we give clear instruction on whether it should be abandoned, or how it can be adapted to be acceptable.
Defect resolution:
- Security and critical bugs are fixed in a reasonable timeframe.
- Test failures are resolved within a reasonable timeframe.
New features:
- We don’t commit to active feature development and/or UX improvement.
- We identify critical missing functionality and/or areas with poor UX.
- We prioritise working on those against other areas for development, recognising that there are a lot of things we could work on.
Releases:
- SemVer is followed.
- Stable releases at least once every 3 months, unless there have been no changes.
- Modules only have new releases if there are actually changes.
Dependency Management
Dependencies of supported modules aren’t necessarily supported themselves, but they need to meet these criteria (“Supported Module Dependencies”).
- PHP dependencies are managed via Composer. Where a 3rd party project doesn’t produce their own Composer package, first attempt to get them to produce own, and otherwise create a fork of their package in Composer. Avoid checking the package’s code straight into the repository.
- JavaScript dependencies are managed via npm, with the code checked into the repository. In this way, NPM may have to be installed for those maintaining the module, but not those using it.
- All dependencies must use SemVer.
- Dependencies must have compatible licenses. MIT or BSD licensed are recommended.
- The PHP version support and browser support must match that of your module.
- Bugs and security vulnerabilities introduced by this dependency must be addressed.
- The maintainers of the supported module feel comfortable raising PRs on this dependency.
- We prefer an active working relationship with the module maintainer, and either their commitment to merge our PRs and release new stable releases, or commit rights ourselves.
- Make a forks of a dependency only as a last resort.
We don’t commit to preserving the full functionality or public API of the dependency in future releases, and may replace with alternatives.
Publication
- Silverstripe Supported Modules will be published on silverstripe.org.
- Silverstripe Supported Module Dependencies will also be listed, but will be distinguished from the Supported Modules.
- This page will list the specific versions that are included in each quarterly update.
- Documentation will be hosted in GitHub.
Hosting environment
- Supported Modules must work in the Silverstripe Cloud and Silverstripe Cloud Public Sector hosting environments.
Release cadence
Refer to the Major Release Policy and Minor Release Policy for information about our release cadence for supported modules.