tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00
Code Issues Projects Releases Wiki Activity

Update module development, remove outdated release steps

Browse Source
This commit is contained in:
Will Rossiter 2013-06-15 12:05:40 +12:00
parent 9775204436
commit 8fca3799c3
6 changed files with 163 additions and 270 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/en/misc/contributing/index.md
View File

@ -1,9 +1,11 @@
# Contributing # Contributing
Any open source product is only as good as the community behind it. You can participate by sharing Any open source product is only as good as the community behind it. You can
code, ideas, or simply helping others. No matter what your skill level is, every contribution counts. participate by sharing code, ideas, or simply helping others. No matter what
your skill level is, every contribution counts.
See our [high level overview on silverstripe.org](http://silverstripe.org/contributing-to-silverstripe) on how you can help out. See our [high level overview on silverstripe.org](http://silverstripe.org/contributing-to-silverstripe)
on how you can help out.
Or, for more detailed guidance, read one of the following pages: Or, for more detailed guidance, read one of the following pages:

5
docs/en/misc/index.md
View File

@ -1,10 +1,9 @@
# Misc # Misc
This section is dedicated to going to detail about an assortment of topics which don't necessary fit into other documentation This section is dedicated to going to detail about an assortment of topics which
sections. don't necessary fit into other documentation sections.
* [Coding conventions](coding-conventions): Guidelines and standards for code formatting and documentation * [Coding conventions](coding-conventions): Guidelines and standards for code formatting and documentation
* [Contributing](contributing): How you can be a part of the SilverStripe Open Source community * [Contributing](contributing): How you can be a part of the SilverStripe Open Source community
* [Module release process](module-release-process): Creating and looking after a module
* [Release process](release-process): Describes the Framework and CMS release process * [Release process](release-process): Describes the Framework and CMS release process
* [SS markdown](ss-markdown): Markdown syntax for our technical documentation * [SS markdown](ss-markdown): Markdown syntax for our technical documentation

241
docs/en/misc/module-release-process.md
View File

@ -1,241 +0,0 @@
# 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 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
[github.com](http://www.github.com) (see [issue reporting guidelines](/misc/contributing/issues)).
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/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 ["docsviewer" module](https://github.com/silverstripe/silverstripe-docsviewer) 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](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/documentation)
* [Contributing to SilverStripe](contributing)
* [Submit your Module](http://silverstripe.org/modules/manage/add)
* [subversion](subversion)

5
docs/en/misc/release-process.md
View File

@ -1,7 +1,6 @@
# Release Process # Release Process
Describes the process followed for "core" releases (mainly the `framework` and `cms` modules). Describes the process followed for "core" releases (mainly the `framework` and `cms` modules).
For other modules, we've compiled a helpful guide for a good [module release process](module-release-process).
## Release Maintainer ## Release Maintainer
@ -18,8 +17,8 @@ Release dates are usually not published prior to the release, but you can get a
reviewing the release milestone on github.com. Releases will be reviewing the release milestone on github.com. Releases will be
announced on the [release announcements mailing list](http://groups.google.com/group/silverstripe-announce). announced on the [release announcements mailing list](http://groups.google.com/group/silverstripe-announce).
Releases of the *cms* and *framework* modules are coupled at the moment, they follow the same numbering scheme. Module Releases of the *cms* and *framework* modules are coupled at the moment, they
releases are documented separately in [module-release-process](module-release-process). follow the same numbering scheme.
## Release Numbering ## Release Numbering

169
docs/en/topics/module-development.md
View File

@ -2,24 +2,34 @@
## Introduction ## Introduction
Creating a module is a good way to re-use abstract code and templates across multiple projects. SilverStripe already has Creating a module is a good way to re-use abstract code and templates across
certain modules included, for example "framework" and "cms". These two modules are the core functionality and multiple projects. SilverStripe already has certain modules included, for
templating for any initial installation. If you're wanting to add generic functionality that isn't specific to your example "framework" and "cms". These two modules are the core functionality and
templates for any initial installation.
If you're wanting to add generic functionality that isn't specific to your
project, like a forum, an ecommerce package or a blog you can do it like this; project, like a forum, an ecommerce package or a blog you can do it like this;
1. Create another directory at the root level (same level as "framework" and "cms") 1. Create another directory at the root level (same level as "framework" and
2. You must create an `_config/` directory inside your module directory, else SilverStripe will not include it "cms")
2. You must create an _config.php inside your module directory, else
SilverStripe will not include it
3. Inside your module directory, follow our [directory structure guidelines](/topics/directory-structure#module_structure) 3. Inside your module directory, follow our [directory structure guidelines](/topics/directory-structure#module_structure)
As long as your module has a `_config.php` file inside it, SilverStripe will
automatically include any PHP classes from that module.
## Tips ## Tips
Try and keep your module as generic as possible - for example if you're making a forum module, your members section Try and keep your module as generic as possible - for example if you're making a
shouldn't contain fields like 'Games You Play' or 'Your LiveJournal Name' - if people want to add these fields they can forum module, your members section shouldn't contain fields like 'Games You
Play' or 'Your LiveJournal Name' - if people want to add these fields they can
sub-class your class, or extend the fields on to it. sub-class your class, or extend the fields on to it.
If you're using Requirements to include generic support files for your project like CSS or Javascript, and want to If you're using Requirements to include generic support files for your project
override these files to be more specific in your project, the following code is an example of how to do so using the like CSS or Javascript, and want to override these files to be more specific in
init() function on your module controller classes: your project, the following code is an example of how to do so using the init()
function on your module controller classes:
:::php :::php
class Forum_Controller extends Page_Controller { class Forum_Controller extends Page_Controller {
@ -36,22 +46,147 @@ init() function on your module controller classes:
} }
This will use `<projectname>/css/forum.css` if it exists, otherwise it falls back to using `forum/css/forum.css`. This will use `<projectname>/css/forum.css` if it exists, otherwise it falls
back to using `forum/css/forum.css`.
## Conventions
### Configuration
SilverStripe has a comprehensive [Configuration](/topics/configuration) system
built on YAML which allows developers to set configuration values in core
classes.
If your module allows developers to customize specific values (for example API
key values) use the existing configuration system for your data.
// use this in your module code
$varible = Config::inst()->get('ModuleName', 'SomeValue');
Then developers can set that value in their own configuration file. As a module
author, you can set the default configuration values.
// yourmodule/_config/module.yml
---
Name: modulename
---
ModuleName:
SomeValue: 10
But by using the Config system, developers can alter the value for their
application without editing your code.
// mysite/_config/module_customizations.yml
---
Name: modulecustomizations
After: "#modulename"
---
ModuleName:
SomeValue: 10
If you want to make the configuration value user editable in the backend CMS,
provide a extension to [SiteConfig](/reference/siteconfig).
## Publication ## Publication
If you wish to submit your module to our public directory, you take responsibility for a certain level of code quality, If you wish to submit your module to our public directory, you take
adherence to conventions, writing documentation, and releasing updates. See [contributing](/misc/contributing). responsibility for a certain level of code quality, adherence to conventions,
writing documentation, and releasing updates. See
[contributing](/misc/contributing).
### Composer and Packagist
SilverStripe uses [Composer](/installation/composer/) to manage module releases
and dependencies between modules. If you plan on releasing your module to the
public, ensure that you provide a `composer.json` file in the root of your
module containing the meta-data about your module.
For more information about what your `composer.json` file should include,
consult the [Composer Documentation](http://getcomposer.org/doc/01-basic-usage.md).
A basic usage of a module for 3.1 that requires the CMS would look similar to
this:
{
"name": "yourname/silverstripe-modulename",
"description": "..",
"type": "silverstripe-module",
"keywords": ["silverstripe", ".."],
"license": "BSD-3-Clause",
"authors": [{
"name": "Your Name",
"email": "Your Email"
}],
"require": {
"silverstripe/framework": ">=3.1.x-dev,<4.0"
}
}
Once your module is released, submit it to [Packagist](https://packagist.org/)
to have the module accessible to developers.
### Versioning
Over time you may have to release new versions of your module to continue to
work with newer versions of SilverStripe. By using composer, this is made easy
for developers by allowing them to specify what version they want to use. Each
version of your module should be a separate branch in your version control and
each branch should have a `composer.json` file explicitly defining what versions
of SilverStripe you support.
<div class="notice" markdown='1'>
The convention to follow for support is the `master` or `trunk` branch of your
code should always be the one to work with the `master` branch of SilverStripe.
Other branches should be created as needed for other SilverStripe versions you
want to support.
</div>
For example, if you release a module for 3.0 which works well but doesn't work
in 3.1.0 you should provide a separate `branch` of the module for 3.0 support.
// for module that supports 3.0.1. (git branch 1.0)
"require": {
"silverstripe/framework": "3.0.*",
}
// for branch of the module that only supports 3.1 (git branch master)
"require": {
"silverstripe/framework": ">=3.1.*",
}
You can have an overlap in supported versions (e.g two branches for 3.1) but you
should explain the differences in your README.md file.
If you want to change the minimum supported version of your module, make sure
you create a new branch which continues to support the minimum version as it
stands before you update the main branch.
## Reference ## Reference
**How To:** ### How To:
* [Add a link to your module in the main SilverStripe Admin Menu](/reference/leftandmain) * [How to customize the CMS Menu](/howto/customize-cms-menu)
* [How to extend the CMS interface](/howto/extend-cms-interface)
**Useful Links:** ### Reference:
Provide custom functionality for the developer via:
* [DataExtension](/reference/dataextension)
* [SiteConfig](/reference/siteconfig)
* [Page types](/topics/page-types)
Follow SilverStripe best practice:
* [Partial Caching](/reference/partial-caching)
* [Injector](/reference/injector)
## Useful Links
* [Introduction to Composer](http://getcomposer.org/doc/00-intro.md)
* [Modules](modules) * [Modules](modules)
* [Module Release Process](module-release-process) * [Directory structure guidelines](/topics/directory-structure#module_structure)
* [Debugging methods](/topics/debugging) * [Debugging methods](/topics/debugging)
* [URL Variable Tools](/reference/urlvariabletools) - Lists a number of page options, rendering tools or special URL variables that you can use to debug your SilverStripe applications * [URL Variable Tools](/reference/urlvariabletools) - Lists a number of page options, rendering tools or special URL variables that you can use to debug your SilverStripe applications

1
docs/en/topics/modules.md
View File

@ -106,4 +106,3 @@ and comes with the same caveats.
## Related ## Related
* [Modules Development](/topics/module-developement) * [Modules Development](/topics/module-developement)
* [Module Release Process](/misc/module-release-process)