12 KiB
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.
Once you have created a module, login at silverstripe.org and submit your module
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.
Principles
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 _config.php
(for instance the ecommerce module works out of the box, and you can easily set up a payment provider), aiding a pleasant
user experience.
Code
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
Maintenance
- 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 open.silverstripe.org.
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.
Documentation
You should have both developer documentation and user documentation, and keep them updated with your releases. See Producing OSS: "Documentation" and our contributing guide.
README file
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
The 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 "sapphiredocs" 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:
- Use of trac to keep your bugs and feature requests organised
- 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.
Release Branches
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.
See SVN Book: "Release Branches", Producing OSS: "Release Branches" and Producing OSS: "Stabilizing a release" for more details.
Release Candidates
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
a 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)
See "ReleaseBranches" chapter and "Tags" chapter.
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
Changelogs
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").
A good 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.