Commit c0b25472 authored by MikeyMJCO's avatar MikeyMJCO
Browse files

Merge branch 'lifecycleCriteria' into 'master'

Update Lifecycle: extension types, workflow, review criteria

See merge request !966
parents bc7c2533 c4e76d21
......@@ -22,14 +22,14 @@ With the extension life-cycle described here, we seek to build an ecosystem that
Should we expect this to work for most users? Should we expect it 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 road bumps should be expected. A project may be "Incubation" for days or months or years.
Work in Progress
: A work-in-progress project offers zero support, stability, or maintenance. It may be useful for discussion, finding collaborators, or proving a concept.
Stable
: A stable project has undertaken significant efforts to ensure that it works and continues working in the future. It has a strong quality-signal.
: A stable 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 road bumps should be expected.
Reviewed Extension
: A Reviewed Extension has undertaken significant efforts to ensure that it works and continues working in the future. It has a strong quality-signal. It has been reviewed by the members of the community and is available for automatic distribution, meaning that it can be installed directly from the CiviCRM administrative interface.
Deprecated
: 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).
......@@ -39,13 +39,15 @@ Deprecated
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.
: This project is managed by individuals or organizations in the ecosystem. All design, support, and maintenance are at the discretion of the maintainers of the extension.
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.
Core Extensions
: The project is included in the main CiviCRM code base (civicrm-core). The extension is managed by the Core Team as well as Mergers for CiviCRM core. The code of the extension is usually included in the main Git repository, under the [ext](https://github.com/civicrm/civicrm-core/tree/master/ext) directory. One exception for historical reasons is the iATS extension, which is maintained as a Contributed extension, and bundled with core releases during the packaging stage.
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.
: 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. See [Abandoned Extensions](#abandoned-extensions).
This document focuses on Contributed extensions, since Core Extensions follow the processes of core itself and are perceived as mostly a more clean way to manage the Core codebase.
### Support Model
......@@ -81,37 +83,29 @@ Technical Metrics
## 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 [extension directory](https://civicrm.org/extensions) 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 by the maturity and stewardship of the project -- with a few basic rules of thumb:
- The author always registers their extension on `civicrm.org` by creating an `extension` node.
- *Official* extensions are subject to more scrutiny than *Contributed* extensions.
- *Experimental*, *Incubation*, and *Deprecated* extensions have simple, open processes -- such as *Self-Assessment* or *Informal Discussion*.
- *Stable* extensions require some kind of *Formal Review*.
- The authors must register their extension on `civicrm.org` by creating an `extension` node.
- *Stable* extensions have simple, open processes -- such as *Self-Assessment* or *Informal Discussion*.
- *Reviewed 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 their 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.
| Stable | Contributed | Formal Review (light) | On `lab.civicrm.org`, the author requests a formal peer review (at https://lab.civicrm.org/extensions/extension-review-requests/issues ) . Once the reviewer is satisfied, they mark the node in `civicrm.org` as Stable. | In app, go to "Add New" and choose the extension.
| Stable | 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.
| Deprecated | 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.
| Deprecated | 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.
| Maturity | Primary Quality Signal | How does an author get their extension designated as X? | How does a user download an extension with X designation? |
| ------------- | ----------------------------- | ----------------------------------------------------- | --------------------------------------------------------- |
| Work in Progress | Self-Assessment | In `civicrm.org`, the author creates an "extension" node and flags it as "Work in Progress". | Locate the extension on the website. The extension might have official releases, or it might be necessary to use Git (follow the instructions from the Git repository).
| Stable | Self-Assessment | In `civicrm.org`, the author creates an "extension" node and flags it as "Stable". | Locate the extension on the website. The extension should have official releases that administrators can download and then manually copy to the 'ext' directory of their CiviCRM installation.
| Reviewed Extension | Formal Review | On `lab.civicrm.org`, the author requests a formal peer review (at https://lab.civicrm.org/extensions/extension-review-requests/issues ) . Once the review is completed, an administrator of the Extension Directory marks the node in `civicrm.org` as "available for automatic distribution". | In app, go to "Add New" and choose the extension.
| Deprecated | Self-Assessment | In `civicrm.org`, the author marks the "extension" node as deprecated and announces to a high-visibility medium. | Locate the extension on the website. View a block which says, "Install Instructions", which includes drush/wp-cli commands.
## Formal Review Process {:#formal-review}
Extensions must pass a *Formal Review* to become designated as *Stable* and made available for automated distribution through CiviCRM's in-app Extension management screen.
The review process assess several criteria, and 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).
Extensions must pass a *Formal Review* to become designated as a *Reviewed Extension* and made available for automated distribution through CiviCRM's in-app Extension management screen.
### Who can review?
* Contributed extensions must be reviewed by at least one peer/contributor.
* Official extensions must be reviewed by at least one senior member of core team.
Any community member can review an extension. The final validation is made by the Extension Directory administrators, which may rely on the community review or their own review. Having community reviews helps accelerate the review time.
### Becoming an extensions reviewer
......@@ -179,32 +173,28 @@ Reviewers should follow these steps to conduct an extension review for automated
### Criteria for passing a review {:#review-criteria}
| Category | Criterion | Required for<br>*contributed*<br>extensions? | Required for<br>*official*<br>extensions? |
|------ | ----- | :-----------------------------: | :---------------------: |
| Admin | Code is licensed under AGPLv3+, GPLv2+, LGPLv2+, MIT/X11, or BSD-2c | **Required** | **Required** |
| Admin | Code is published on github.com or lab.civicrm.org | **Required** | **Required** |
| Admin | Extension name uses "org.civicrm.*" namespace | No | *Suggested* |
| Admin | Bus factor >= 2 | No | *Suggested* |
| Admin | Access to project is granted to infra team | No | *Suggested* |
| Admin | Release schedule is aligned with core | No | *Suggested*
| Coding | All code complies with civicrm-core style guidelines | No | **Required**
| Coding | Automated tests execute within 3 minutes (or less) | No | *Suggested*
| Coding | All dependencies are at similar stage (Ex: A stable project should not depend on an experimental project) | No | **Required**
| Coding | All strings are wrapped in ts() | *Suggested* | **Required**
| Coding | The project does not *override* `PHP` or `TPL` files from civicrm-core | **Required** | **Required**
| Coding | The project does not modify the `SQL` schema of a standard civicrm-core table | **Required** | **Required**
| Coding | The project does not *conflict* with other official projects | *Suggested* | *Suggested*
| Distribution | The project is packaged as a CiviCRM Extension, Drupal Module, Backdrop Module, Joomla Extension, or WordPress plugin | **Required** | **Required**
| Distribution | The project has a stable version (1.0+; not alpha or beta) | **Required** | **Required**
| Distribution | A demo site is provided | *Suggested* | *Suggested*
| QA | The project declares, on the in-app extension management screen, the nature of any changes it makes to existing data or functionality. | **Required** | **Required**
| QA | The project functions in all CMS's (for CiviCRM Extension) | *Suggested* | *Suggested*
| QA | An automated test suite is included | *Suggested* | **Required**
| QA | Project is periodically re-validated with newer versions of CiviCRM and compatibility updates are published | No | **Required**
| QA | All patches are subjected to peer review | No | *Suggested*
| QA | All patches are subjected automated tests | No | **Required**
| Support | Documentation is published | *Suggested* | **Required**
| Support | Issues are tracked in an open, public issue management system | *Suggested* | **Required**
| Category | Criterion | Required? |
|------ | ----- | :-----------------------------: |
| Admin | Code is licensed under AGPLv3+, GPLv2+, LGPLv2+, MIT/X11, or BSD-2c | **Required** |
| Admin | The extension is registered in the Extension Directory and has a unique name/key | **Required** |
| Admin | Code is published on lab.civicrm.org or github.com | **Required** |
| Coding | Code complies with civicrm-core style guidelines | **Required** |
| Coding | Automated tests execute within 3 minutes (or less) | *Suggested* |
| Coding | All dependencies are at similar stage (Ex: A stable project should not depend on an experimental project) | **Required** |
| Coding | All user-visible strings are wrapped in ts() in such a way that translation works properly | **Required** |
| Coding | The project does not *override* `PHP` or `TPL` files from civicrm-core | **Required** |
| Coding | The project does not modify the `SQL` schema of a standard civicrm-core table | **Required** |
| Distribution | The project is packaged as a CiviCRM Extension | **Required** |
| Distribution | The project has a stable version (1.0+; not alpha or beta) | **Required** |
| Distribution | A demo site is provided | *Suggested* |
| QA | The project declares, on the in-app extension management screen, the nature of any changes it makes to existing data or functionality. | **Required** |
| QA | The project functions in all CMS's | **Required** |
| QA | An automated test suite is included | *Suggested* |
| QA | Project is periodically re-validated with newer versions of CiviCRM and compatibility updates are published | No |
| QA | All patches are subjected to peer review | *Suggested* |
| QA | All patches are subjected automated tests | **Suggested** |
| Support | Documentation is published | *Suggested* |
| Support | Issues are tracked in an open, public issue management system | **Required** |
### Acting on review results
......@@ -232,21 +222,19 @@ If a review indicates that the extension should be approved, the reviewer should
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 ("Stable" or "Incubation") [where technically applicable]
| Distribution | Project may be bundled into the standard CiviCRM tarballs. | "Official" projects ("Stable" 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 ("Stable" or "Incubation")
| Marketing | The project is included in official marketing literature about CiviCRM | "Stable", "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 ("Stable" or "Incubation")
| Support | The project may have its own space or component on "lab.civicrm.org" | "Official" projects (regardless of stability)
| Action Type | Benefit/Resource/Privilege |
| ----------- | ---------------------------- |
| Communication | A public channel for discussions on https://chat.civicrm.org |
| Communication | Blog posts on civicrm.org |
| Communication | Announcements using CiviMail on civicrm.org |
| Admin | The project may be hosted on https://lab.civicrm.org/extensions for Git hosting and issue tracking |
| Distribution | Discovery on the in-app screen (ie. automated distribution) |
| Distribution | Project may be bundled into the standard CiviCRM tarballs (Core Extensions). |
| Distribution | The project is listed in `http://civicrm.org/extensions` (Contributed Extensions) |
| Distribution | Test and demo sites on civicrm.org may include the extension. |
| Marketing | The project may be included in official marketing literature about CiviCRM |
| QA | The `civicrm.org` build-bot runs extension tests for PRs (own repo) |
| QA | The `civicrm.org` build-bot runs extension tests for PRs (civicrm-core repo) |
## Obsolete Extensions
......@@ -300,4 +288,4 @@ When an extension author has stopped being responsive:
1. Open an issue on the issue tracker of the project. [See example request](https://github.com/ChrisChinchilla/CiviCRM-eWay-recurring-payment-processor/issues/59)
2. Wait 14 days for a response.
3. If no response (or if the author confirms it is abandoned), create a ticket in the [Extensions Review Request issues queue](https://lab.civicrm.org/extensions/extension-review-requests/issues) asking for the extension to be either a) de-listed for in-app installation, or b) unpublished from civicrm.org
\ No newline at end of file
3. If no response (or if the author confirms it is abandoned), create a ticket in the [Extensions Review Request issues queue](https://lab.civicrm.org/extensions/extension-review-requests/issues) asking for the extension to be either a) de-listed for in-app installation, or b) unpublished from civicrm.org
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment