This document contains information about a future release and not the current stable version (3.0).
Be aware that information on this page may change and API's may not be stable for production use.
Module Maintenance and Release Procedures
Creating a module
One of the best ways that you can contribute to SilverStripe is by developing a module for SilverStripe.
If you do, we would love to host your module and have you become an official module maintainer on our site. Please read our "Contributing to SilverStripe" overview.
It's very important to us that users of SilverStripe can come to expect a level of quality from the core product and any modules running on it. In order to provide this, we require certain things from module maintainers.
The following documentation describes aspects of subversion, you can read about similiar strategies for git on a free online book.
Strive for features you add to the CMS to be innovatively usable by a content editor rather than a web-developer.
Think Wordpress and Apple. Most modules should work by merely placing the code in your SilverStripe installation and
running /dev/build. Provide a default set of configuration options that are easily changed in
(for instance the
ecommerce module works out of the box, and you can easily set up a payment provider), aiding a pleasant
Each line of code you write should be version controlled, in version control systems like subversion or Git. There's lots of services that are freely available for opensource projects, including wiki and bugtracker functionality (e.g. Google Code for Subversion or Github for Git).
- Add your module to silverstripe.org/modules (and keep the version compatibility information current)
- Follow our coding-conventions
- Write unit tests and functional tests covering code bundled with the module - see testing-guide
- Ensure your code is localizable
- Create releases (see "Module Releases" below)
- Ensure that your module is patched to always work with the latest SilverStripe release, and note these compatibilities on your modules page on silverstripe.org
- Be involved in our community
- Subscripe to our developer mailing list and be available to answer questions on the forum.
- Attend our weekly core discussions on IRC as regularly as you can.
- Create an issue tracker so your users can file bugs and feature requests (see "Feedback and Bugtracking" below)
- Create a roadmap and milestones outlining future release planning
Feedback and Bugtracking
Both Google Code and github.com provide their own bugtracker - we encourage you to use any built-in tools that come with your version control hoster. Most Silverstripe-maintained modules have their bugtracker on github.com (see issue reporting guidelines).
Providing bugtracking is a major form of communicating with your users in an efficient way, and will provide a good overview of outstanding work and the stability of your code to an interested user.
If the user community finds bugs that shouldn't be included in the next stable release, you will need to release another release candidate. If your release candidate is found to be stable, then you can create the stable release.
Each module should have a
README.md file in the project root in
markdown format, roughly following this template:
# <MODULENAME> Module ## Maintainer Contact * <FULLNAME> (Nickname: <NICKNAME>, <EMAIL>) ## Requirements * <Specific SilverStripe version, PHP, MySQL, ...> ## Documentation <Links to the wiki, blog posts, etc> ## Installation Instructions <Step by step instructions> ## Usage Overview <Highlevel usage, refer to wiki documentation for details> ## Known issues <Popular issues, how to solve them, and links to tickets in the bugtracker>
The docs/ folder
README.md file might get a bit long for bigger modules, and you might want to break it up into multiple files
that you can link from the
README.md file. Example:
mymodule/ README.md code/ docs/ installation.md tutorial.md howto-search-mymodule.md
The "docsviewer" module can be used
to list and render content inside a
docs/ folder (although it is not required, Markdown is designed
to be readable in plain text as well).
What do you get?
In return for all your hard work in putting a high-quality module on the site, the SilverStripe project has the following options to support you:
- Advertising of your module on the http://silverstripe.org/modules/ modules page once it has reached a beta stage and shown to meet our requirements above.
- We might showcase your module on our blog and/or newsletter, when it's first released and/or when a major version with significant new features is released. We'll work with you to publicise it on other blogs too (it helps if you deliver screenshots and screencasts)
- More influence in suggesting changes to the core product
- Kudos on Ohloh
Releasing a Module
If you are a module maintaienr, you will be responsible for creating new releases of the module. Releases are important for each codebase to provide stability for its users, and clearly communicate dependencies/requirements.
In order to ensure stability, the first thing we do when making a release is to create a release branch. This branch will exist for the duration of the testing and release candidate phase. The key is that you should only commit bugfixes to this branch. This lets you focus on getting a stable version of module ready for release, and new features can still be added to trunk.
Creating a release branch is a simple
svn cp command. In the example below, (modulename) would be something like
"ecommerce" or "flickrservice", and (releasenumber) would be something like "0.2.1" (see
Producing OSS: Release Numbering)
svn cp http://svn.silverstripe.com/open/modules/(modulename)/trunk http://svn.silverstripe.com/open/modules/(modulename)/branches/(releasenumber)
Once you have created a release branch, you should do some testing of the module yourself. Try installing it on a new site, and existing site, use the different features, and if possible, install on a couple of different servers.
Once you've done your own testing, it's time to create a release candidate (RC). This is a copy of your module that
will be sent to the developer community for testing and feedback. Creating a release candidate is a matter of executing
svn cp command.
Note: If you are the only developer on the module, and you aren't going to be creating any new features for the duration of the release cycle, then you can get away with creating your RCs directly from trunk instead of creating a release branch. For major modules, we advise against this, but for very simple modules, going through the whole release process might be overkill.
svn cp http://svn.silverstripe.com/open/modules/(modulename)/branches/(releasenumber) http://svn.silverstripe.com/open/modules/(modulename)/tags/rc/(releasenumber)-rc1 svn co http://svn.silverstripe.com/open/modules/(modulename)/tags/rc/(releasenumber)-rc1 (modulename) tar czf (modulename)_(releasenumber)-rc1.tar.gz (modulename)
Stabilizing A Release
After you have put a release candidate out for testing and no-one has found any bugs that would prevent a release, you
can create the stable release! Please: The stable release should always be a copy of a release candidate. Even if
"there's just one tiny bug to fix", you shouldn't release that bug fix onto a stable release - there is always the risk
that you inadvertently broke something! As you might guess,
svn cp is used to create the final release, and then an
export to a tar.gz.
svn cp http://svn.silverstripe.com/open/modules/(modulename)/tags/rc/(releasenumber)-rc2 http://svn.silverstripe.com/open/modules/(modulename)/tags/(releasenumber) svn export http://svn.silverstripe.com/open/modules/(modulename)/tags/(releasenumber) (modulename) tar czf (modulename)_(releasenumber).tar.gz (modulename)
Announcing a Release or Release Candidate
- See Producing OSS: "Announcing Releases"
- Update your documentation in the sourcecode, wiki and README
- Add your release to the silverstripe.org/modules listing
- Announce the release on silverstripe-announce. Include a changelog, the download link and instructions for filing bug reports.
- If this release is a major release, our marketing guys will strive to announce it on the main silverstripe.com blog as well
Each release you make should contain
CHANGELOG file in the project root with a highlevel overview of additions and
bugfixes in this release. The
svn log command gives you all commit messages for a specific project, and is a good
start to build a changelog (see "Examining historical changes" chapter).
Depending on the volume of changes, it is preferred that you summarize these messages in a more "digestible"
form (see Producing OSS: "Changes vs. Changelog").
CHANGELOG example from the subversion project itself:
Version 1.5.2 (29 Aug 2008, from /branches/1.5.x) http://svn.collab.net/repos/svn/tags/1.5.2 User-visible changes: * Set correct permissions on created fsfs shards (r32355, -7) * Pass client capabilities to start-commit hook (issue #3255) * Disallow creating nested repositories (issue #3269) Developer-visible changes: * make libsvn_ra_neon initialization thread-safe (r32497, r32510) Version 1.5.1 (24 Jul 2008, from /branches/1.5.x) http://svn.collab.net/repos/svn/tags/1.5.1 ...
Release Branch Maintenance
This is also the time to remove the release branch from the subversion tree - we don't want to have lots of branches on the source tree to confuse everyone. However, before you do this, you will need to merge your changes back to the trunk.