/docs/en/misc/module-release-process.md
Markdown | 242 lines | 167 code | 75 blank | 0 comment | 0 complexity | 324306d8440017c8f1ad69d6df2a18de MD5 | raw file
- # 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"](http://silverstripe.org/contributing-to-silverstripe/) overview.
- Once you have created a module, login at [silverstripe.org](http://silverstripe.org) and
- [submit your module](http://silverstripe.org/modules/manage/add)
- 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.
- <div class="hint" markdown="1">
- The following documentation describes aspects of subversion, you can read about similiar
- strategies for git on a [free online book](http://progit.org/book).
- </div>
- ### 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](http://subversion.tigris.org) or [Git](http://gitscm.com). There's lots of services that are freely
- available for opensource projects, including wiki and bugtracker functionality
- (e.g. [Google Code for Subversion](http://code.google.com) or [Github for Git](http://github.com)).
- * Add your module to [silverstripe.org/modules](http://silverstripe.org/modules) (and keep the version compatibility information current)
- * Follow our [coding-conventions](coding-conventions)
- * Write unit tests and functional tests covering code bundled with the module - see [testing-guide](/topics/testing)
- * Ensure your code is [localizable](/topics/i18n)
- ### Maintenance
- * Create releases (see ["Module Releases"](#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 [irc:our weekly core discussions on IRC](irc/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"](module-release-process#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](http://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"](http://producingoss.com/en/getting-started.html#documentation) and our
- [contributing guide](contributing#writing-documentation).
- ### README file
- Each module should have a `README.md file` in the project root in
- [markdown format](http://daringfireball.net/projects/markdown/), 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](http://open.silverstripe.org/browser/modules/sapphiredocs/trunk) 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](http://open.silverstripe.org) 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](http://www.ohloh.net/projects/5034?p=SilverStripe+CMS)
- ## 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](http://producingoss.com/en/development-cycle.html#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"](http://svnbook.red-bean.com/en/1.5/svn.branchmerge.commonpatterns.html#svn.branchmerge.commonpatterns.release),
- [Producing OSS: "Release Branches"](http://producingoss.com/en/release-branches.html) and
- [Producing OSS: "Stabilizing a release"](http://producingoss.com/en/stabilizing-a-release.html) 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](http://svnbook.red-bean.com/en/1.5/svn.branchmerge.commonpatterns.html#svn.branchmerge.commonpatterns.release)
- and ["Tags" chapter](http://svnbook.red-bean.com/en/1.5/svn.branchmerge.tags.html).
- ### 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"](http://producingoss.com/en/testing-and-releasing.html#release-announcement)
- * Update your [documentation](module-release-process#documentation) in the sourcecode, wiki and README
- * Add your release to the [silverstripe.org/modules](http://silverstripe.org/modules) listing
- * Announce the release on [silverstripe-announce](http://groups.google.com/group/silverstripe-announce). Include a
- [changelog](module-release-process#changelogs), the download link and instructions for filing bug reports.
- * If this release is a major release, our [marketing guys](http://silverstripe.com/contact/) will strive to announce it
- on the main [silverstripe.com blog](http://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](http://svnbook.red-bean.com/en/1.5/svn.tour.history.html)).
- 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"](http://producingoss.com/en/packaging.html#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.
- ## See Also
- * [Module Development](/topics/module-development)
- * [Documentation Guide](contributing#writing-documentation)
- * [Contributing to SilverStripe](http://silverstripe.org/contributing-to-silverstripe/)
- * [Submit your Module](http://silverstripe.org/modules/manage/add)
- * [subversion](subversion)