Extension Lifecycle¶

This document describes the process of publishing extensions within the CiviCRM ecosystem and reporting abandoned extensions.

Background¶

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 collaboration means that we're all engaged in some give-and-take. We alternate between two roles:

Consumers: Sometimes we're the receivers. We want to quickly browse the available extensions, pick the ones which look best, and install them. We expect the extensions to work — both now and going forward (with future upgrades).
Developers: Sometimes we're the providers. We enjoy building great functionality, and want to invite people to use our products, but need to juggle the publishing tasks (like testing and maintenance releases) with the goals and resources provided by our bosses and clients.

With the extension lifecycle described here, we seek to build an ecosystem that balances the needs of both consumers and developers.

Definitions¶

Project Maturity¶

Should we expect this to work for most users? Should we expect it to work in 6 months?

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 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).

Stewardship¶

Who manages a project? Who decides whether the project is experimental? Or maintained? Or unmaintained?

Contributed: 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.
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 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. See 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¶

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, they 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 their 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 extension directory 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 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	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¶

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.

Extension maintainers can request a review by opening an issue on the Extension Review Request project. Please use the "extension-review" issue template.

Who can review?¶

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¶

Everyone is encouraged to become a reviewer, regardless of their experience or skills. Even a partial review helps move things forward. Non-technical people can also be of great help with making sure that extension descriptions are clear and concise.

To become an extensions reviewer, please take the following steps:

Set up accounts on these sites (if you need help, reach out through the community resources)
1. civicrm.org
2. lab.civicrm.org - log in using your civicrm.org account
Visit the Extensions Review Request project to see the open requests.

Once you submit a review, we will upgrade your permissions so that you can edit issue summaries (ex: to check boxes, not that it is particularly important). If we forget, you can ask in the extensions channel of the CiviCRM chat.

Selecting an Extension for Review¶

Choose an open extension review request.

Consider the following criteria while choosing:

Readiness: The issue should contain a link to its listing on the civicrm.org extension directory. If no such link is provided, please request one in a comment on the issue, and move on to another issue.
Age of request: All else being equal, older review requests should be reviewed first.
Affinity/interest: Reviewers may wish to select an extension which relates to functionality in which they have an interest or with which they're especially familiar. On the other hand, there's no requirement to have any special knowledge of the extension's functionality if one is prepared to invest a little extra effort in the review.
Neutrality: Reviewers should not have been involved in the development of the extension. Employment or contracting relationships can introduce conflicts of interest. Reviews should be conducted by a neutral third party.

Conducting a Review¶

Reviewers should follow these steps to conduct an extension review for automated distribution:

You will be reviewing the extension on at least one supported CMS. You don't need to test that it works on every CMS. To that end, ensure you have such a site available, on which you can be free to experiment with untested extensions like the one you're reviewing.

Tip

By definition, the extension you're reviewing is unreviewed. You probably do not want to install it on a live site. You can use Buildkit to create the CMS environment on-demand (but any dev site will do).
Download and install the most recent release of the extension.

Important

If you clone the git repository of the extension, be sure to check out the tag for the most recent stable release. Don't assume that the master branch is ready for review, and reviews require that the extension have a stable release (not alpha or beta releases, which are not listed in the Extension Directory).
If possible, observe that the extensions meets the criteria listed below. If you cannot review a criteria, either because it is too technical or too long to do, don't worry! We usually do not review every single line of code of extensions, but if later someone discovers a non-compliant item, then we will work with the extension maintainers to get it resolved, or remove the reviewed status.
Try to make the extension misbehave in any potential edge cases that occur to you. Note any significant failures.
Create a document to show the details of your review. It can be a google doc or .odt file or something similar.
- Copy/paste the criteria table into your review document.
- Add an additional column to the table for your comments.
- Summarize all your tests and findings, positive or negative.
- Copy-paste (in markdown), attach or link to your review document in the "Extension Review Request" issue.
- Here is a markdown template that you can copy-paste as a Gitlab comment. You can also copy-paste it into your favorite text editor, and paste the link or attach it as a file in a comment. Do what it convenient for you, as long as we can clearly see which points were reviewed.
Use all of the information gained in the review to decide whether to approve the extension.

Criteria for passing a review¶

The review steps are divided into three categories to allow different people with different skills sets to work on them.

Feel free to ask on the extensions channel of the CiviCRM chat if you have any questions about the criteria below. Most of them, except for the "coding" section, are administrative, as long as you know where to look (admittedly, not obvious at first). If you do not know how to install an extension, you can skip that part too. Any review, even partial, will helps move things forward.

Distribution¶

Packaging: The project is packaged as a CiviCRM Extension (and not a Drupal module, WordPress plugin, etc). It is usually mentioned in the README.md or you can look for a info.xml file in the code repository.
Registration: The extension is registered in the CiviCRM Extension Directory. It should be linked on the review request issue.
License: The extension is licensed under AGPLv3+, GPLv2+, LGPLv2+, MIT/X11, or BSD-2c. This should be documented in the README.md or LICENSE file of the code repository.
Repository: The extension code is published on lab.civicrm.org or github.com. See the "View on Github" or "View on Gitlab" link on the extension's page.
Stable: The extension has a stable version such as 1.0.0, not alpha or beta. You can look at the version numbers of the releases on the extension's page.
Stable Dependencies: All dependencies are at similar stage. Ex: the extension should not depend on an un-reviewed extension. Dependencies should be listed in the info.xml file of the extension, under the "requires" tag (if the tag is not there, it means that the extension does not have dependencies).
Updates: The extension is periodically updated to support newer versions of CiviCRM. For example, the extension's page has a list of regular releases and there are no open issues about bugs for newer versions.
Adoption: The extension has more than 25 reported users according to the CiviCRM stats displayed on the extension's page. This usually shows that the extension is relevant to a certain number of people and generally means that if there are bugs, someone will open an issue for it.

Support¶

All-CMS: The extension supports all variations of CiviCRM (Standalone and on a CMS). There are no known incompatibilities with a CMS. For example, the extension description does not mention "this extension only works on WordPress" and there are no open bug reports that mention a specific CMS.
Public Issues: Issues (bug reports, new features) are tracked either on CiviCRM's Gitlab or on a public Github repository.
Directory Description: The extension's page on civicrm.org has a clear and concise description. It should describe the nature of any changes it makes to existing data or functionality. It should include screenshots if possible.
In-app Description: The description on civicrm.org should also be in the info.xml file of the extension and in the README, so that people can also see it in the in-app extension management screen.

Code¶

For developers who may be doing a code review, we fully understand that it is not realistic to review every single line of code. If possible, do a few quick spot-checks. Otherwise, these criteria are meant as guidelines for developers. If someone opens a bug report on these issues, we expect extension maintainers to resolve them quickly. Otherwise, we might remove the "reviewed" status of the extension.

Code Style: Code complies with civicrm-core style guidelines.
Translation: All user-visible strings implement the recommended practices so that translation will work correctly.
Overrides: The project does not override PHP or TPL files from civicrm-core.
Schema: The project does not modify the SQL schema of a standard civicrm-core table.
Security: The project respects the privacy and security of CiviCRM. For example, it does not share data without consent, pingback, auto-upgrade by itself, patch code unexpectedly, override a core feature. Exceptions may be allowed if it is the main feature of the extension and it explicitly says so in its project description.

Optional¶

The following criteria are not required, but encouraged. Reviewers do not need to evaluate these criteria:

Docs: Documentation is published on https://docs.civicrm.org.
Peer-Review: Patches are done using merge-requests and are subject to peer review.
Tests: The extension has a test suite so that it can be easily tested on newer versions of CiviCRM.

Acting on review results¶

If the extension needs work¶

If a review indicates that the extension needs further improvement before it can be approved, the reviewer should add a comment to the issue to notify the issue reporter that the extension needs work; specifically mention the issues that prevent approval as well as other items which the developer may want to improve at their discretion.

Continue monitoring the issue for updates from the developer, and respond in a timely way to answer questions or to conduct a follow-up review after changes have been made.

If the extension is approved¶

If a review indicates that the extension should be approved, the reviewer should take these steps:

Add a comment to the issue to notify the issue reporter that the extension has been reviewed for automated distribution. Also mention any items which the developer may want to improve, even though they did not prevent the extension from being approved.
Congratulate yourself on your contribution to CiviCRM. Thank you!

An administrator of the extension directory will then:

Edit the extension's node on civicrm.org to set the field "Reviewed and ready for automated distribution?" to "Yes: This Extension Release has been reviewed and is ready for automated distribution."
Add a comment to the issue to notify the issue reporter that the extension has been approved for automated distribution.
Close the issue.
Optionally: Mention the extension approval in the extensions channel at chat.civicrm.org.

Benefits¶

Based on a project's maturity and stewardship, it may be eligible to use resources from civicrm.org.

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¶

Sometimes an extension's functionality becomes part of CiviCRM Core, or is otherwise redundant, and the extension should no longer be used.

At that point it can be added to the Extension Compatibility List with one or more of the following flags:

"obsolete" - extension will not be installable, and will be labeled "Obsolete" in the in-app Manage Extensions page. Any dependencies to an obsolete extension will be ignored.
"disable" - extension will be automatically disabled by the CiviCRM upgrader.
"uninstall" - extension will be automatically uninstalled by the CiviCRM upgrader.
"force-uninstall" - extension code will be prevented from loading at all (necessary if the extension's presence would cause a fatal error such as a redeclared class).

For example, APIv4 was moved from an extension into core in 5.19. The extension was marked "obsolete": 5.19 and "force-uninstall": true to prevent php fatal errors due to the same classes now being in core. Any extensions declaring org.civicrm.api4 as a dependency in their info.xml would continue to work without it, as the dependency would be ignored as of 5.19.

Abandoned Extensions¶

A CiviCRM Extension may be abandoned when the project author is no longer releasing updates and/or is not responding to support requests within 14 days or has expressly stated that they are no longer actively maintaining the project.

The CiviCRM community has two options for managing an abandoned extension.

Transfer Ownership to a New Maintainer¶

When an extension author has stopped being responsive:

and there are important bugs in the extension
and someone else has offered to take over maintenance.

Procedure¶

Open an issue on the issue tracker of the project. See example request
Wait 14 days for a response.
If no response, or if a response clearly indicates the author has no intention to maintain the project going forward,
1. Create an issue in the Extensions Review Request issues queue indicating that you are interested in stepping up as the new maintainer of the extension.
2. In the request, please tell us a bit about your plans and motivations to maintain the extension, and link to the issue where you tried to contact the original developer.
The extensions team will handle the migration of the extension:
1. Migrate the extension's Git repository to CiviCRM's Gitlab, if it was previously hosted elsewhere
2. Change the node author for the extension from civicrm.org
3. Add the new author as a co-maintainer on civicrm.org
4. Change the Git URL for the extension, if it was moved to Gitlab
5. Add the new maintainer on the project on CiviCRM's Gitlab.

Request Removal of the Extension¶

When an extension is superseded by another extension, or
When an extension has critical bugs and is not being updated by the maintainer.

Procedure¶

Open an issue on the issue tracker of the project. See example request
Wait 14 days for a response.
If no response (or if the author confirms it is abandoned), create a ticket in the Extensions Review Request issues queue asking for the extension to be either a) de-listed for in-app installation, or b) unpublished from civicrm.org