diff --git a/docs/en/misc/contributing/index.md b/docs/en/misc/contributing/index.md index 92c4ee193..2d9d90412 100644 --- a/docs/en/misc/contributing/index.md +++ b/docs/en/misc/contributing/index.md @@ -1,9 +1,11 @@ # Contributing -Any open source product is only as good as the community behind it. You can participate by sharing -code, ideas, or simply helping others. No matter what your skill level is, every contribution counts. +Any open source product is only as good as the community behind it. You can +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: diff --git a/docs/en/misc/index.md b/docs/en/misc/index.md index baed69c51..4cbe26745 100644 --- a/docs/en/misc/index.md +++ b/docs/en/misc/index.md @@ -1,10 +1,9 @@ # Misc -This section is dedicated to going to detail about an assortment of topics which don't necessary fit into other documentation -sections. +This section is dedicated to going to detail about an assortment of topics which +don't necessary fit into other documentation sections. * [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 -* [Module release process](module-release-process): Creating and looking after a module * [Release process](release-process): Describes the Framework and CMS release process * [SS markdown](ss-markdown): Markdown syntax for our technical documentation \ No newline at end of file diff --git a/docs/en/misc/module-release-process.md b/docs/en/misc/module-release-process.md deleted file mode 100644 index 8a0341e93..000000000 --- a/docs/en/misc/module-release-process.md +++ /dev/null @@ -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. - -
-The following documentation describes aspects of subversion, you can read about similiar -strategies for git on a [free online book](http://progit.org/book). -
- -### 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: - - - # Module - - ## Maintainer Contact - - * (Nickname: , ) - - ## Requirements - - * - - ## Documentation - - - - ## Installation Instructions - - - - ## Usage Overview - - - - ## Known issues - - - -### 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) diff --git a/docs/en/misc/release-process.md b/docs/en/misc/release-process.md index 79cfa4e51..235e637ad 100644 --- a/docs/en/misc/release-process.md +++ b/docs/en/misc/release-process.md @@ -1,7 +1,6 @@ # Release Process 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 @@ -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 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 are documented separately in [module-release-process](module-release-process). +Releases of the *cms* and *framework* modules are coupled at the moment, they +follow the same numbering scheme. ## Release Numbering diff --git a/docs/en/topics/module-development.md b/docs/en/topics/module-development.md index 964e051d3..33d61210d 100644 --- a/docs/en/topics/module-development.md +++ b/docs/en/topics/module-development.md @@ -2,24 +2,34 @@ ## Introduction -Creating a module is a good way to re-use abstract code and templates across multiple projects. SilverStripe already has -certain modules included, for example "framework" and "cms". These two modules are the core functionality and -templating for any initial installation. If you're wanting to add generic functionality that isn't specific to your +Creating a module is a good way to re-use abstract code and templates across +multiple projects. SilverStripe already has certain modules included, for +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; -1. Create another directory at the root level (same level as "framework" and "cms") -2. You must create an `_config/` directory inside your module directory, else SilverStripe will not include it +1. Create another directory at the root level (same level as "framework" and +"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) +As long as your module has a `_config.php` file inside it, SilverStripe will +automatically include any PHP classes from that module. + ## Tips -Try and keep your module as generic as possible - for example if you're making a 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 +Try and keep your module as generic as possible - for example if you're making a +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. -If you're using Requirements to include generic support files for your project like CSS or Javascript, and want to -override these files to be more specific in your project, the following code is an example of how to do so using the -init() function on your module controller classes: +If you're using Requirements to include generic support files for your project +like CSS or Javascript, and want to override these files to be more specific in +your project, the following code is an example of how to do so using the init() +function on your module controller classes: :::php class Forum_Controller extends Page_Controller { @@ -27,7 +37,7 @@ init() function on your module controller classes: public function init() { if(Director::fileExists(project() . "/css/forum.css")) { Requirements::css(project() . "/css/forum.css"); - }else{ + } else { Requirements::css("forum/css/forum.css"); } parent::init(); @@ -36,22 +46,147 @@ init() function on your module controller classes: } -This will use `/css/forum.css` if it exists, otherwise it falls back to using `forum/css/forum.css`. +This will use `/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 -If you wish to submit your module to our public directory, you take responsibility for a certain level of code quality, -adherence to conventions, writing documentation, and releasing updates. See [contributing](/misc/contributing). +If you wish to submit your module to our public directory, you take +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. + +
+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. +
+ +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 -**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) -* [Module Release Process](module-release-process) +* [Directory structure guidelines](/topics/directory-structure#module_structure) * [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 diff --git a/docs/en/topics/modules.md b/docs/en/topics/modules.md index 38115e0eb..6d114e61f 100644 --- a/docs/en/topics/modules.md +++ b/docs/en/topics/modules.md @@ -105,5 +105,4 @@ and comes with the same caveats. ## Related -* [Modules Development](/topics/module-developement) -* [Module Release Process](/misc/module-release-process) \ No newline at end of file +* [Modules Development](/topics/module-developement) \ No newline at end of file