Revise concepts/extensions and create community info doc on developin…

…g extensions.

community/coding-style-guide.html

@@ -0,0 +1,7 @@
+---
+title: "Coding Style Guide"
+weight: 10
+description: "Format your code the Symphony way."
+---
+
+Coding style/standards here.

community/developing-extensions.md

@@ -0,0 +1,63 @@
+---
+title: "Contributing to Symphony: Extensions"
+weight: 5
+description: "Give back to the community by making Symphony more awesome."
+---
+
+The [core philosophy][tao] of Symphony's development is to keep the core simple and to keep the systems it uses discrete. This is why all but the basic functionality—the design pattern that makes Symphony distinct from another CMS—resides in extensions, and why so few extensions are bundled with the core. Installing and maintaining extensions is an easy way to make your Symphony build powerful while keeping it flexible.
+
+Developing new extensions, or maintaining and improving existing ones, is a great way to begin contributing to the Symphony community if you're not ready, or interested, in [working on the core][core]. You'll get a better idea of how Symphony is structured, how it works, and you'll make connections with other Symphony users.
+
+## Look Around
+
+Someone else might have built an extension that already serves your needs. Check [SymphonyExtensions.com][] or the [download section][download] of the website, or ask around in the [forums][]. Even if you can't find an extension that matches your exact use case, you might find one you can fork and use as a template for your extension. Or, if you find an unmaintained or abandoned extension, you could take it over and improve it rather than starting from scratch.
+
+## Plan It
+
+Once you've determined that you want to build a new extension, start by determining *how* your extension is going to accomplish its goal. That is:
+
+- Do you need to provide custom [data sources][]? Custom [events][]?
+- Will you need to make custom backend pages?
+- Is your extension going to bundle an external library or rely on an API?
+
+## Build It
+
+We have a [tutorial on developing extensions][tutorial] that walks you through how to create a simple extension from scratch. You should also look at the source code of other extensions out there, particularly those that are similar to what yours will do.
+
+### Other Useful References
+
+- [Coding Style Guide]({{site.baseurl/community/coding-style-guide.html}})
+- [Symphony API](http://getsymphony.com/learn/api/)
+- [GitHub organization](https://github.com/symphonycms/)
+
+## Describe It
+
+Make sure your extension has a valid `extension.meta.xml` file, as per the [Symphony Extension Metadata Schema][schema]. This will let Symphony and other APIs automatically load information about your extension. You need this even if you don't plan on publishing your extension. Make sure you note:
+
+- the version(s) compatible with your extension;
+- any special installation or download instructions; and
+- whether the extension is considered stable ("released"), experimental, or unmaintained.
+
+For humans, you'll want to make sure there is a `README` file with equivalent information.
+
+You should also choose a license for your extension. Symphony uses the [MIT License][mit], so we recommend that—plus, it's short and easy to add. You can even just copy it from Symphony and change the copyright information at the top. However, you are not required to use this license—but you should make it clear what license your code is under, so others are aware of how they can make changes.
+
+## Push It
+So you built an extension! Congratulations. Sometimes you'll only need an extension for a very narrow case, so maybe others won't find much use in it. However, if you think you're ready to make your extension public, here's the best way you can share:
+
+1. Publish the extension as a repo on GitHub.
+1. Go to [SymphonyExtensions.com][], sign in with your GitHub account, and add a new extension using the repo you just published.
+1. (Optional) Announce your new extension on the [forums][] (and ask for feedback!).
+1. Respond to issues and pull requests through GitHub. Your `master` branch should always represent a "stable" build of the extension. You may or may not want to maintain a public `integration` branch for ongoing development, though it's recommended.
+
+While you certainly don't have to use Git and GitHub, this is where ongoing Symphony development discussions happen, so it is the best way to integrate with the community and stay in the loop.
+
+[core]: {{site.baseurl}}/community/contributing-to-symphony.html
+[data sources]: {{site.baseurl}}/concepts/data-sources/
+[events]: {{site.baseurl}}/concepts/events/
+[forums]: http://getsymphony.com/discuss/
+[mit]: https://github.com/symphonycms/symphony-2/blob/master/LICENCE
+[schema]: http://symphonyextensions.com/schemas/extension/1.0/
+[SymphonyExtensions.com]: http://symphonyextensions.com/
+[tao]: {{site.baseurl}}/guides/articles/the-tao-of-symphony.html
+[tutorial]: {{site.baseurl}}/guides/tutorials/developing-an-extension.html

concepts/extensions/delegates.md

@@ -4,27 +4,37 @@ weight: 2
 description: "Delegates allow developers to manipulate input and output and perform other tasks during the generation of back-end and front-end pages."
 ---
 
-#### Overview
+Delegates are functions in Symphony's core that allow [extension][ext] developers to intervene at key moments in the generation of a back-end or front-end Symphony page. The delegate will usually provide a contextually relevant PHP object (for instance a page object or an event object) that the developer can then work with and pass back to the system for further processing.
 
-Delegates are functions in Symphony's core that allow <a href="http://getsymphony.com/learn/concepts/extensions/">extension</a> developers to intervene at key moments in the generation of a back-end or front-end Symphony page. The delegate will usually provide a contextually relevant PHP object (for instance a page object or an event object) that the developer can then work with and pass back to the system for further processing.
+# Subscribing to Delegates
 
-#### Usage
+Extensions can subscribe to delegates by declaring a `getSubscribedDelegates()` function in the [`extension.driver.php`][struct] file, like this:
 
-Extensions can subscribe to delegates by declaring a `getSubscribedDelegates()` function in the <a href="http://getsymphony.com/learn/concepts/view/extension-file-structure/#extensiondriverphp">extension.driver.php</a> file, like this:
-
-<pre><code>
-  public function getSubscribedDelegates(){
+{% highlight php %}
+  public function getSubscribedDelegates()
+  {
     return array(
       array(
         'page' => '/delegatepage/',
         'delegate' => 'DelegateName',
         'callback' => 'extensionFunction'
       ),
     );
-  }</code></pre>
+  }
+{% endhighlight %}
+
+<aside class="note">
+  <p>Delegate subscriptions are kept in the database. Changing which delegates your extension subscribes to requires that you enable/disable the extension for your changes to take effect.</p>
+</aside>
 
-`getSubscribedDelegates()` is expected to return an array of subscriptions, each of which is an array consisting of three key/value pairs: **page**, **delegate**, and **callback**. The first two values are defined by the delegate itself (see the list below). The last value is the name of a callback function provided by the extension.
+`getSubscribedDelegates()` is expected to return an array of subscriptions, each of which is an array consisting of three key/value pairs: **page**, **delegate**, and **callback**. The first two values are defined by the delegate itself. The last value is the name of a callback function provided by the extension.
 
 During normal system processing, delegates fire `notifyMembers()` functions, which allows any subscribed extensions to intervene before processing continues.
 
-See the <a href="http://getsymphony.com/learn/api/2.3/delegates/">API Docs</a> for a full list of delegates.
+# List of Delegates
+
+Please refer to the [API documentation on delegates][api] for a complete list of delegates. Every entry links to the GitHub-hosted copy of the file where the delegate is defined. If you want to know in which version a delegate was first introduced, click through to the file and check the delegate's `@since` parameter.
+
+[api]: http://www.getsymphony.com/learn/api/2.5.2/delegates/
+[ext]: {{site.baseurl}}/concepts/extensions/
+[struct]: {{site.baseurl}}/concepts/extensions/extension-file-structure.html

concepts/extensions/extension-file-structure.md

@@ -1,24 +1,16 @@
 ---
 title: "Extension File Structure"
 weight: 3
-description: "The Extension File Structure enables Symphony to detect and load extension files automatically."
+description: "How Symphony detects and loads extensions automatically."
 ---
 
-#### Overview
+The Extension File Structure is a set of layout and naming conventions for [extensions]({{site.baseurl}}/concepts/extensions/) that enables them to be automatically detected and loaded by Symphony. You must follow these conventions when creating an extension.
 
-The Extension File Structure is a set of layout and naming conventions for <a rel="concept" href="extensions">extension</a> files that enables them to be automatically detected and loaded by Symphony.
+## Directory Structure
 
-#### Usage
+Extensions should be structured as follows. Note that the only required files are `extension.driver.php` and `extension.meta.xml`. The remaining directories and files can be included as needed.
 
-When creating an extension, simply follow the conventions outlined below.
-
-#### Details
-
-##### Overview
-
-Extensions should be structured as follows. Note that the only required file is extension.driver.php. The remaining directories and files can be included as needed.
-
-<pre><code>
+~~~
   yourextension/
     assets/
         sample.js
@@ -40,48 +32,49 @@ Extensions should be structured as follows. Note that the only required file is
     text-formatters/
         formatter.sample.php
     extension.driver.php
-    license
-    README</code></pre>
+    LICENSE
+    README
+~~~
 
-##### assets/
+### assets/
 
-Though not actually used for auto-inclusion, placing CSS, JavaScript, and image files in an assets directory is a Symphony convention
+Though not actually used for auto-inclusion, placing CSS, JavaScript, and image files in an assets directory is a Symphony convention.
 
-##### content/
+### content/
 
-The files in the content directory are autoincluded and used to render back-end pages. The file content.sample.php would render a page at `/symphony/extension/yourextension/sample`. content.index.php is viewable at `/symphony/extension/yourextension`.
+The files in the `content` directory are autoincluded and used to render back-end pages. The file content.sample.php would render a page at `/symphony/extension/yourextension/sample`. content.index.php is viewable at `/symphony/extension/yourextension`.
 
-##### data-sources/
+### data-sources/
 
-Any <a rel="concept">data sources</a> to be provided by an extension must be placed here for auto-inclusion.
+Any [data sources]({{site.baseurl}}/concepts/data-sources/) to be provided by an extension must be placed here for auto-inclusion.
 
-##### events/
+### events/
 
-Any <a rel="concept">events</a> to be provided by an extension must be placed here for auto-inclusion.
+Any [events]({{site.baseurl}}/concepts/events/) to be provided by an extension must be placed here for auto-inclusion.
 
-##### fields/
+### fields/
 
-Any <a rel="concept">field types</a> to be provided by an extension must be placed here for auto-inclusion.
+Any [fields]({{site.baseurl}}/concepts/sections/fields.html) to be provided by an extension must be placed here for auto-inclusion.
 
-##### lang/
+### lang/
 
 Any localization dictionaries to be provided by an extension must be placed here for auto-inclusion.
 
-##### lib/
+### lib/
 
-Like the assets folder, the lib folder is not actually used for auto-inclusion but is conventionally used to store custom library files used by the extension.
+Like the `assets` folder, the `lib` folder is not actually used for auto-inclusion but is conventionally used to store custom library files used by the extension.
 
-##### text-formatters/
-Any text formatters to be provided by an extension must be placed here for auto-inclusion.
+### text-formatters/
+Any [text formatters]({{site.baseurl}}/concepts/sections/text-formatters.html) to be provided by an extension must be placed here for auto-inclusion.
 
-##### extension.driver.php
-The extension driver, used to initiate, enable, uninstall, and upgrade an extension and to subscribe to <a rel="concept">delegates</a>. This file is required.
+### extension.driver.php
+The extension driver, used to initiate, enable, uninstall, and upgrade an extension and to subscribe to [delegates]({{site.baseurl}}/concepts/extensions/delegates.html}}. This file is required.
 
-##### license or licence
-A text file detailing the license(s) used by the extension.
+### extension.meta.xml
+An XML file that follows the [Symphony Extension Metadata Schema](http://symphonyextensions.com/schemas/extension/1.0/) to provide information about the extension, its version history, and its release notes. Both Symphony itself and other APIs, like the one at [SymphonyExtensions.com], use this.
 
-##### README or README.markdown
-The extension's README file. Conventionally contains basic information (extension name, version, and release date), developer information (name, email, and website) and installation and usage notes.
+### LICENSE or LICENCE
+A text file detailing the license(s) used by the extension. Note that Symphony uses the [MIT License](https://github.com/symphonycms/symphony-2/blob/master/LICENCE), so it is recommended (but not required) that you use the same or a compatible license.
 
-#### The Big Picture
-The extension file structure is an important part of Symphony's **Extension API** (forthcoming).
+### README (or README.markdown, or README.md)
+The extension's README file. Conventionally contains basic information (extension name, version, and release date), developer information (name, email, and website) and installation and usage notes. Because most Symphony extensions live on GitHub, Markdown is the conventional way to format these files but is not a requirement.

concepts/extensions/index.md

@@ -4,30 +4,41 @@ weight: 1
 description: "Extensions add specialized functionality to the lean, mean Symphony core."
 ---
 
-#### Overview
+Extensions are add-ons that can provide additional functionality for your Symphony project. Some more common uses for extensions include providing additional [field types][fields] and [text formatters][text], enhancing the [admin interface][admin], and even bundling entirely new features.
 
-Extensions are add-ons that can provide additional functionality for your Symphony project. Some more common uses for extensions include providing additional <a rel="concept">field types</a> and <a rel="concept">text formatters</a>, enhancing the <a rel="concept">admin interface</a>, and even bundling entirely new features. Symphony’s open **Extension API** (forthcoming) makes it easy for developers to contribute new extensions.
-
-#### Usage
+## Using Extensions
 
 Extensions must be placed in the `extensions/` folder of a Symphony installation in order to be made available to the system.
 
-They can be managed in the admin interface, under `System > Extensions`. Individual or bulk management is possible by selecting extensions and using the "With Selected" dropdown to Enable, Disable, or Uninstall.
+They can be managed in the admin interface, under **System > Extensions**. Individual or bulk management is possible by selecting extensions and using the "With Selected" dropdown to Enable, Disable, or Uninstall.
+
+For more information, see [Managing Extensions][manage].
+
+## Default Extensions
+
+There are eight default extensions. These are bundled with the Symphony CMS download archive. If you clone Symphony from its Git repo, you will need to checkout the `bundle` branch and initialize the extension submodules therein.
+
+- [Markdown](https://github.com/symphonycms/markdown)
+- [Maintenance Mode](https://github.com/symphonycms/maintenance_mode)
+- [Select Box Link Field](https://github.com/symphonycms/selectbox_link_field)
+- [JIT Image Manipulation](https://github.com/symphonycms/jit_image_manipulation)
+- [Export Ensemble](https://github.com/symphonycms/export_ensemble)
+- [Debug DevKit](https://github.com/symphonycms/debugdevkit)
+- [Profile DevKit](https://github.com/symphonycms/profiledevkit)
+- [XSS Filter](https://github.com/symphonycms/xssfilter)
 
-#### Details
+## Finding Extensions
 
-There are seven default extensions:
+The best places to find extensions, and to check for updates, are [SymphonyExtensions.com][] and the [extension download section][download] of the Symphony website.
 
-Extension Name | Description
--------------- | -----------
-<a rel="concept" href="devkits#debug-devkit">Debug Devkit</a> | Provides front-end debugging interface via the ?debug param.
-Export Ensemble | Enables the creation of <a rel="concept">ensembles</a> in the admin interface.
-<a rel="concept" href="field-types#select-box-link">Select Box Link</a> field | Field type that enables the creation of persistent relationships between section entries.
-<a rel="concept">JIT Image Manipulation</a> | Enables on-the-fly manipulation of images via specially formed src URLs.
-<a rel="concept">Maintenance Mode</a> | Enables maintenance mode.
-Markdown Text Formatter | Provides Markdown text formatter which can be applied to text area fields.
-<a rel="concept" href="devkits#profile-devkit">Profile Devkit</a> | Provides front-end profiling interface via the ?profile param.
+## Developing Extensions
 
-#### The Big Picture
+- [Contributing to Symphony: Extensions]({{site.baseurl}}/community/developing-extensions.html)
+- [How to Develop an Extension]({{site.baseurl}}/guides/tutorials/developing-an-extension.html)
 
-Extensions can provide all kinds of features for a Symphony project. The Symphony website hosts a <a href="/download/extensions">library of extensions</a> with far-ranging capabilities. Among other things, extensions can provide custom <a rel="concept">data sources</a>, <a rel="concept">events</a>, field types, text formatters, localization dictionaries, and more.
+[admin]: {{site.baseurl}}/concepts/admin-interface/
+[download]: http://getsymphony.com/download/extensions/
+[field]: {{site.baseurl}}/concepts/sections/fields.html
+[manage]: {{site.baseurl}}/getting-started/managing-extensions.html
+[SymphonyExtensions.com]: http://symphonyextensions.com/
+[text]: {{site.baseurl}}/concepts/sections/text-formatters.html

getting-started/managing-extensions.md

@@ -67,6 +67,8 @@ If you installed your extensions as git submodules, then from your Symphony inst
         $ git pull origin master
 
     (You will likely need to checkout the `master` or equivalent branch because submodules, by default, point to a detached HEAD.)
+
+    Alternatively, you can run `git submodule update --remote extensions/extension_name`, which will pull the latest commit from the 'stable' branch that your submodule tracks.
 1. Go to the Extensions page in the backend, and follow the same step as above to update the extension in your database.
 1. If you are satisfied everything is well, then commit the submodule changes to your parent repo.