Merge pull request #60 from GinkgoFJG/EXT-21-extension-review-doc

EXT-21: Migrated/updated documentation around extension publication and automated distribution

docs/extensions/basics.md

@@ -10,9 +10,7 @@ Todo:
 **CiviCRM Extensions** are packaged pieces of functionality that extend
 CiviCRM's out-of-the-box functionality, independent of CMS plaform.
 
-This section covers how to write extensions. See the [extension life cycle
-page](/extend-stages) for background on the publishing and review process for
-[published extensions](https://civicrm.org/extensions).
+This section covers how to write extensions.
 
 ## Extension Names
 
@@ -45,17 +43,6 @@ different short-name, but that requires extra work.
     by the www-data user. You will need to make this file readable by
     your development user account for civix to work.
 
-## General overview
-
-[]( fixme paragraph this section into above notes )
-
-If you haven't already, you need to configure a local directory to store
-extensions.
-For instructions, see
-[Extensions](https://wiki.civicrm.org/confluence/display/CRMDOC/Extensions)
-You may also want to review the
-[Extension Reference](https://wiki.civicrm.org/confluence/display/CRMDOC/Extension+Reference) page for technical details.
-
 ### 0. Decide
 Writing an extension is a great way to implement a new feature – but it may be
 unnecessary if someone else has already implemented that feature. If you're not
@@ -70,14 +57,18 @@ plugins. If you're considering another way, look at the
 to help decide.
 
 ### 1. Install civix
-Some tasks in the process of writing an extension require boiler-plate code. To
+Some tasks in the process of writing an extension require boilerplate code. To
 reduce the amount of work required to find, understand, and adapt the
-boiler-plate code, one should install the CiviCRM extension builder, civix.
+boilerplate code, one should install the CiviCRM extension builder, civix.
 Civix is a command-line tool which generates code for some common development
 tasks.
 
 >> See [https://github.com/totten/civix/](https://github.com/totten/civix/)
 
+>> For more information on the boilerplate civix generates for you, in
+   particular the extension manifest file (info.xml), see the [Extension
+   Reference](https://wiki.civicrm.org/confluence/display/CRMDOC/Extension+Reference).
+
 ### 2. Develop
 To get started with development, one should usually follow the steps in
 "[Create a Module
@@ -89,7 +80,18 @@ conventions closely resemble those of CiviCRM Core and of CiviCRM-Drupal
 modules. Module extensions are fully supported in CiviCRM 4.2+.
 
 ### 3. Publish
-The CiviCRM Extensions Directory provides a way to publicize your extension –
-and it even provides easy, in-app distribution.
-
-See: [Publish](http://wiki.civicrm.org/confluence/display/CRMDOC/Publish+an+Extension),
+The CiviCRM ecosystem is built on the belief that non-profit organizations can
+serve themselves best by collaborating in development of their data-management
+applications. As staff, volunteers, and consultants for non-profit organizations,
+we can share our new enhancements and extensions -- and build a richer whole for
+the entire ecosystem.
+
+Extension authors may make their extensions available to the larger CiviCRM
+community by publishing them in the [Extensions Directory](https://civicrm.org/extensions).
+>> See: [Publish](extensions/publish)
+
+Extensions which undergo a [formal review](extend-stages#formal-review) may be
+distributed in-app. Approved extensions can be [installed
+directly](https://docs.civicrm.org/user/en/master/introduction/extensions/#installing-extensions)
+into CiviCRM via the user interface, lowering the barrier to entry for many users.
+>> See: [Automated Distribution](extensions/publish#automated-distribution)

docs/extensions/publish.md

+# Publishing Extensions
+
+Publishing an extension is an easy way to:
+
+-   recruit collaborators for a project
+-   increase your user base and, along with it, the potential for:
+    -   contributed bug fixes
+    -   new use cases
+    -   feature requests and project funding
+-   bring positive attention to your organization
+-   share a useful feature or set of configurations with worthy nonprofit and
+    community organizations
+
+While you could simply publish your extension to a web-based code repository
+like GitHub, publishing through the
+[CiviCRM Extensions Directory](http://civicrm.org/extensions) makes it easy for
+others to find and download it. Moreover, CiviCRM-native extensions which undergo a
+formal review can even be distributed in-application to CiviCRM sites running
+version 4.2 or greater.
+
+The following instructions assume you will be publishing a CiviCRM-native
+extension (i.e., a CMS-agnostic extension). Instructions for CMS-specific
+extensions are similar; differences are noted in [Notes for CMS-specific
+extensions](#notes-for-cms-specific-extensions).
+
+## Publishing a CiviCRM extension
+
+CiviCRM's publishing process automates a number of tasks related to maintaining
+your extensions. Just provide some basic information about the extension, and
+the rest is taken care of for you! Subsequent releases will automatically be
+detected, published, and submitted for translation.
+
+### Prerequisites:
+
+-   The extension code is published in a public GitHub repository.
+-   The extension manifest (`info.xml`) is in the root of the repository.
+-   The extension manifest is
+    [valid](https://wiki.civicrm.org/confluence/display/CRMDOC/Extension+Reference#ExtensionReference-Tagsininfo.xml).
+-   The name of the extension repository (e.g., *https://github.com/civicrm/org.civicrm.legcase.git*)
+    matches the extension's fully qualified name (.e.g, *org.civicrm.legcase*) or
+    its short name as specified by the `file` tag in `info.xml` (e.g., *legcase*).
+-   Each release of the extension is "tagged" in the git repository with a
+    ["PHP-standardized" version number string](http://php.net/manual/en/function.version-compare.php).
+    Version number strings may optionally be prefixed with a "v."
+    -   Valid tag names: "v1.2.3", "1.2.3", "v1.2-beta3", "1.2-beta3"
+    -   Invalid (ignored) tag names: "stable", "1.2-prerelease"
+
+### Publishing an extension:
+
+-   [Register](https://civicrm.org/user/register) for an account on civicrm.org if you
+    do not already have one.
+-   [Login](https://civicrm.org/user) to civicrm.org and [create a new extension
+    node](http://civicrm.org/node/add/extension). If you see an "Access Denied"
+    message, you'll need to email [info@civicrm.org](mailto:info@civicrm.org)
+    with your user id and request permission to publish extensions.
+-   Fill out all required fields. Also provide the "Git URL" for the extension.
+-   Within a day, you will receive an email notifying you that the extension
+    was published on civicrm.org or that a problem with the extension manifest
+    (`info.xml`) prevented publication.
+
+### Publishing subsequent releases:
+
+-   Update the extension manifest and push the changes to your GitHub repository.
+    At minimum you'll need to increment the version number.
+-   Create a git "tag" which matches the version in the manifest and push it, e.g.:
+
+        git tag -a v1.2.0
+        git push origin v1.2.0
+
+-   Within a day, you will receive an email notifying you that the release
+    was published on civicrm.org or that a problem with the extension manifest
+    prevented publication.
+
+### Notes for CMS-specific extensions
+
+CMS-specific extensions are developed for a single CMS / CiviCRM environment
+(e.g. Drupal 7 + CiviCRM, Joomla 2.5 + CiviCRM, etc.), typically using the
+extension framework of the CMS in question (for example, webform_civicrm is
+packaged as a Drupal module which invokes Drupal hooks).
+
+These extensions can be published on the CiviCRM.org extensions directory, but
+CiviCRM does not provide in-application distribution for them. We recommend
+publishing them to the CiviCRM directory and to the relevant CMS extension
+directory (drupal.org, etc.) to take advantage of the distribution system
+provided by the CMS.
+
+To publish a CMS-specific extension, follow the steps outlined above for
+[publishing an extension](#publishing-an-extension). (Note that the
+[prerequisites](#prerequisites) do not apply, that the extension manifest will
+be named and formatted according to the conventions of the CMS and not CiviCRM's
+`info.xml`, and that you may choose not to supply a "Git URL.") On the resulting
+release node, you will find a link "Add Extension Release." On this screen, you
+will provide release information as well as a link from which the extension may
+be downloaded.
+
+If you develop new version(s) of your extension, you can submit additional
+releases at any time.
+
+## Automated distribution
+
+The best way to reap the benefits of publishing your extension is to make it as
+easy as possible for others to install it. With just a few clicks, CiviCRM site
+administrators can view and install CiviCRM extension releases which meet
+certain criteria. To be eligible for automated distribution:
+
+-   The extension must be published in the Extensions Directory.
+-   One of the extension's maintainers must [request an extension review
+    request](https://issues.civicrm.org/jira/secure/CreateIssue!default.jspa?selectedProjectId=10400&issuetype=10000).
+-   The extension manifest must flag the release as "stable."
+-   The extension manifest must include a link to online documentation.
+-   The extension manifest must flag the release as compatible with CiviCRM
+    version 4.2 or greater.
+-   The release must be CMS-agnostic, and it must install without errors or
+    notices from the Manage Extensions page of a site running a stable release
+    of CiviCRM. Errors installing in any of the supported CMSes are grounds for
+    holding an extension back from automated distribution.
+-   The extension must provide the promised functionality. Serious bugs and
+    errors found by a CiviCRM community extension moderator exploring the
+    functionality of the extension are grounds for holding an extension back
+    from automated distribution.
+
+It is strongly recommended that you [write unit
+tests](https://github.com/civicrm/org.civicrm.testapalooza) for the extension
+and include them in the extension's repository. For an example, see the extension
+[org.civicrm.exampletests](https://github.com/totten/org.civicrm.exampletests).
+
+Once an extension release meets these criteria, the extension will be approved
+for automated distribution by a CiviCRM community extension moderator.
\ No newline at end of file

mkdocs.yml

@@ -47,6 +47,7 @@ pages:
   # - Custom Reports: extensions/custom-reports.md
   # - Custom Searches: extensions/custom-searches.md
   # - Payment Processors: extensions/payment-processor.md
+  - Publish: extensions/publish.md
 - Best Practices:
   - Documentation Style Guide: best-practices/documentation-style-guide.md
 - Core code:

redirects/wiki-crmdoc.txt

 Documentation+Infrastructure+Canary develop
 The+developer+community basics/community
 Create+an+Extension extensions/basics
+Publish+an+Extension extensions/publish
 Before+you+start basics/planning
 Recommendations basics/planning
 The+codebase core/architecture