Merge pull request #13 from totten/master-stages

Add "Extension Lifecycle" chapter

docs/extend-stages.md

+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.
+
+Of course, this sharing arrangement means that many members of the community
+have a split role, e.g.
+
+ * Sometimes, we are consumers. We want to quickly browse the available
+   extensions, pick the ones which look best, and install them. We
+   expect these to just work -- both now and going forward (with future upgrades).
+ * Sometimes, we are developers.  We enjoy building great functionality, and we
+   want to invite people to use our products, but we need to juggle the
+   publishing tasks (like testing and maintenance releases) with the goals 
+   and resources provided by our bosses and clients.
+
+The purpose of this document is to describe the process of publishing
+extensions through the CiviCRM ecosystem.
+
+## Definitions	
+
+ * __Project Maturity__: Should we expect this to work for most users? Should we expect to work in 6 months?
+     * __Experimental__: An experimental project offers zero support, stability, or maintenance. It may be useful for discussion, finding collaborators, or proving a concept.
+     * __Incubation__: An incubation project offers some degree of support, stability, or maintenance. It's probably in use at multiple organizations. However, the levels are not guaranteed; some gaps and roadbumps should be expected. A project may be "Incubation" for days or months or years.
+     * __Maintained__: A maintained project has undertaken significant efforts to ensure that it works and continues working in the future. It has a strong quality-signal.
+     * __Unmaintained__: The project is no longer being maintained. It may work today; but it's liable to break tomorrow (unless someone steps up to manage it).
+ * __Stewardship__: Who manages a project? Who decides whether the project is experimental? Or maintained? Or unmaintained?
+     * __Contributed__: This project is managed by an individual or company in the ecosystem. All design, support, and maintenance are at discretion of the original author.
+     * __Official__: The project is monitored as a community resource. Generally, the original author retains editorial control, but the project receives more strenuous reviews and follows stricter standards with feedback from others in the community.
+     * __Seeking Maintainer__: This project does not have a person or organization responsible for it. If you think the project is useful, feel free to take responsibility for it.
+ * __Support Model__: How do you submit questions and requests about issues?
+     * __Free__: Submit questions and requests to an open bug-tracker.
+     * __Negotiated__: Issues may be reported to open bug-tracker. If the author agrees it is critical or data-loss, he may address it. Otherwise, you need to negotiate a contract.
+     * __Pre-Paid__: The author will not engage in any support discussions unless you have pre-paid for support.
+ * __Quality Signals__: How do we know if an extension is any good?
+     * __Self-Assessment__: An author makes a claim about the stability of his work. (This is a low-tech, low-touch process.)
+     * __Informal Discussion__: One or more experts give gut reactions. (This is a low-tech, high-touch process.)
+     * __Formal Review__: One or more experts assesses the quality, maintainability, best-practices, etc. using formal criteria. (This is a low-tech, high-touch process.)
+     * __Social Metrics__: Data-points (such as #installations or average 5-star rating) is collected from many people. (This is a high-tech, low-touch process.)
+     * __Technical Metrics__: Technical details (such as test-coverage, test-results, style-checks, or cyclomatic complexity) are checked by a bot. (This is a high-tech, low-touch process.)
+
+## Workflow
+
+The database on `civicrm.org` publishes information about available extensions, including maturity and stewardship. 
+This is significant because it affects authors (who publish the extension) and users (who download the extension) and
+determines access to communal resources on `civicrm.org`.  The particulars are determined the maturity and stewardship
+of the project -- with a few basic rules of thumb:
+
+ * The author always registers his extension on `civicrm.org` by creating an `extension` node.
+ * *Official* extensions are subject to more scrutiny than *Contributed* extensions.
+ * *Experimental*, *Incubation*, and *Unmaintained* extensions have simple, open processes -- such as *Self-Assessment* or *Informal Discussion*.
+ * *Maintained* extensions require some kind of *Formal Review*.
+
+Based on these rules, we can fill out a full table of the workflow:
+
+
+| Maturity	| Stewardship	| Primary Quality Signal	| How does an author get his extension designated as X?	| How does a user download an extension with X designation? |
+| ------------- | ------------- | ----------------------------- | ----------------------------------------------------- | --------------------------------------------------------- |
+| Experimental	| Contributed	| Self-Assessment	| In `civicrm.org`, the author creates an "extension" node and flags it as "Experimental".	| Locate the extension on the website. View a block which says, "Install Instructions", which includes drush/wp-cli commands.
+| Experimental	| Official	| Informal Discussion	| As above. *Additionally* The author announces to a high-visibility medium (such as blog or mailing-list). If discussion is persuasive, a senior member of core team flags the project as official.	| Locate the extension on the website. View a block which says, "Install Instructions", which includes drush/wp-cli commands.
+| Incubation	| Contributed	| Self-Assessment	| In `civicrm.org`, the author creates an "extension" node and flags it as "Incubation".	| Locate the extension on the website. View a block which says, "Install Instructions", which includes drush/wp-cli commands.
+| Incubation	| Official	| Informal Discussion	| As above. *Additionally* The author announces to a high-visibility medium (such as blog or mailing-list). If discussion is persuasive, a senior member of core team flags the project as official.	| Locate the extension on the website. View a block which says, "Install Instructions", which includes drush/wp-cli commands.
+| Maintained	| Contributed	| Formal Review (light)	| In JIRA, the author requests a formal peer review.  Once the reviewer is satisfied, he marks the node in `civicrm.org` as Maintained.	| In app, go to "Add New" and choose the extension.
+| Maintained	| Official	| Formal Review (heavy)	| As above. *Additionally* FormalReview criteria are more detailed. Announce to a high-visibility medium. At least one reviewer must be a senior member of the core team.	| In app, go to "Add New" and choose the extension.
+| Unmaintained	| Contributed	| Self-Assessment	| In `civicrm.org`, the author marks the "extension" node as deprecated and announce to a high-visibility medium.	| Locate the extension on the website. View a block which says, "Install Instructions", which includes drush/wp-cli commands.
+| Unmaintained	| Official	| Informal Discussion	| The author announces intent to deprecate in a high-visibility medium. If discussion is persuasive and no alternative maintainer comes forward, a senior member of core team flags the project as official.	| Locate the extension on the website. View a block which says, "Install Instructions", which includes drush/wp-cli commands.
+
+
+## Formal Review
+
+To designate an extension as *Maintained*, someone must conduct a *Formal Review* and assess several criteria.
+As a rule of thumb, *Contributed* extensions are subject to a gentler review (fewer criteria), and *Official*
+extensions are subject to more stringent review (more criteria).
+
+|   	|       | Contributed	| Official |
+|------ | ----- | ----------------------------- | --------------------- |
+| | | Review by at least one peer/contributor	| Review by at least one senior member of core team |
+| Admin	| License code under AGPLv3+, GPLv2+, LGPLv2+, MIT/X11, or BSD-2c	| Required	| Required |
+| Admin	| Publish code on github.com 	| Required	| Required |
+| Admin	| Put the extension name under the "org.civicrm.*" namespace	| Not assessed	| Suggested (Not Required) |
+| Admin	| Bus factor >= 2	| Not assessed	| Suggested (Not Required) |
+| Admin	| Grant project admin access to infra team	| Not assessed	| Suggested (Not Required) |
+| Admin	| Release schedule is aligned with core.	| Not assessed	| Suggested (Not Required)
+| Coding	| All code complies with civicrm-core style guidelines.	| Not assessed	| Required
+| Coding	| Automated tests execute within 3 minutes (or less).	| Not assessed	| Suggested (Not Required)
+| Coding	| All dependencies are at similar stage. (Ex: An incubation project should not depend on a sandbox project.)	| Not assessed	| Required
+| Coding	| Strings are wrapped in ts()	| Suggested (Not Required)	| Required
+| Coding	| The project does not *override* PHP, TPL, JS, or SQL from civicrm-core.	| Required	| Required
+| Coding	| The project does not *conflict* with other official projects.	| Suggested (Not Required)	| Suggested (Not Required)
+| Distribution	| The project is packaged as a CiviCRM Extension, Drupal Module, Backdrop Module, Joomla Extension, or WordPress plugin.	| Required	| Required
+| Distribution	| Have a Maintained (1.0+; not alpha or beta) version	| Required	| Required
+| Distribution	| Provide a demo site	| Suggested (Not Required)	| Suggested (Not Required)
+| QA	| Works in all CMS's (for CiviCRM Extension)	| Suggested (Not Required)	| Suggested (Not Required)
+| QA	| Include an automated test suite	| Suggested (Not Required)	| Required
+| QA	| Periodically re-validate with newer versions of CiviCRM. Publish updates for compatibility.	| Not assessed	| Required
+| QA	| Subject all patches to peer review	| Not assessed	| Suggested (Not Required)
+| QA	| Subject all patches to automated tests	| Not assessed	| Required
+| Support	| Publish documentation	| Suggested (Not Required)	| Required
+| Support	| Track issues in an open, public issue management system	| Suggested (Not Required)	| Required
+
+## Benefits
+
+Based on a project's maturity and stewardship, it may be eligible to use resources from `civicrm.org`.
+
+| Action Type	| Benefit/Resource/Privilege	| Eligibility |
+| - | - | - |
+| Admin	| The project code may be stored in github.com/civicrm/civicrm-core.git.	| "Official" projects (regardless of stability)
+| Admin	| The project code may be stored in github.com/civicrm/{$project}	| "Official" projects (regardless of stability)
+| Communication	| Direct discussions through `chat.civicrm.org` 	| All projects
+| Communication	| Direct discussions through `lists.civicrm.org`	| All projects
+| Communication	| Direct discussions through `wiki.civicrm.org` 	| All projects
+| Distribution	| Discovery on the in-app screen (ie. automated distribution)	| All projects ("Maintained" or "Incubation") [where technically applicable]
+| Distribution	| Project may be bundled into the standard CiviCRM tarballs.	| "Official" projects ("Maintained" or "Incubation")
+| Distribution	| The project is listed in `http://civicrm.org/extensions`	| All projects
+| Distribution	| Test and demo sites on civicrm.org include the extension.	| "Official" projects ("Maintained" or "Incubation")
+| Marketing	| The project is included in official marketing literature about CiviCRM	| "Maintained", "Official" projects
+| QA	| The `civicrm.org` build-bot runs extension tests for PRs (own repo)	| "Official" projects (regardless of stability)
+| QA	| The `civicrm.org` build-bot runs extension tests for PRs (civicrm-core repo)	| "Official" projects ("Maintained" or "Incubation")
+| Support	| The project may have its own space or component on "issues.civicrm.org" (JIRA)	| "Official" projects (regardless of stability)

mkdocs.yml

@@ -20,6 +20,7 @@ pages:
    - General: hook.md
    - Database: hooks-db.md
  - Miscellaneous:
+   - 'Extension Lifecycle': extend-stages.md
    - Markdown: markdownrules.md
    - hookref-old: hookref-old.md
  - Deprecated: