This strategy document sets out what the community of Joomla users, from ordinary non-technical users through to high-level technical developers, can expect from the products that come under the umbrella of the Joomla project.
This is primarily about how we approach and manage change: how we adapt, develop and grow our products in an ever-changing technological landscape; how we communicate to our users and contributors what to expect from our products as they change from one release to the next; and how we guide our contributors towards making the future changes that we want as a community.
The stakeholders in our project have widely varying needs and a balance must be struck between, at one extreme, those for whom any change is unwelcome and all shades to the other extreme of those who thrive on continuous change. Change is essential if our products are to remain relevant to their intended users, so our goal is to manage that change in such a way that we minimise the disruption it can cause.
Since the Joomla project is responsible for more than one product, this strategy is written to be as generic as possible and to allow new products to be added to our portfolio without forcing any extensive re-writes.
This strategy builds on the substantial practical experience of a lot of people over the many years since the project's foundation. The reasoning behind what is written here, and the lessons learned in leading up to it, is outside the scope of the document itself and reference should be made to other sources for that commentary.
1.1 Executive Summary
This document is necessarily rather long because there is a lot of detail that needs to be covered, which means that unfortunately, many people will not read all of it. Recognising that reality, this section attempts to summarise what you need to know and point you to the appropriate sections for additional information.
These are the key points of this strategy:
- The version numbering scheme is your key to understanding the degree of change inherent in a release. The version number is in three parts separated by dots: [major].[minor].[patch]. For example, 2.5.18 has a major number of 2, a minor number of 5 and a patch number of 18. A release which increments the major number is referred to as a major release; one that increments only the minor number is a minor release; and one that increments only the patch number is a patch release. Refer to our Release Policy for further details.
- A release is said to be "backward compatible" with an earlier release if your system continues to work correctly when updated to that release even when other parts of your system were not updated at the same time. However, there are limits to what is covered by backward compatibility and you should read the Backward Compatibility Policy for the full details.
- A major release is the only kind of release where backward compatibility can be intentionally broken. A minor release may add new features and capabilities but it must be backward compatible with the release it replaces. Patch releases are for bug and security fixes only and will not break backward compatibility.
- Releases are either supported or they are not supported. When we say that a release is supported, we mean that all major issues and most minor issues will be addressed in a subsequent release. Refer to Support Policy for further information.
- Within each major series, only the most recent minor release is supported. As soon as a new minor release is made, support for the previous minor release is ended.
- A major series may be declared end-of-life (and hence become unsupported) only after at least 2 years have elapsed since the most recent minor release in that series. What this means is that each time a minor release is made it resets the support clock for that series, thus ensuring that a major series will enjoy extended life for as long as there is sufficient interest in producing minor releases for it. Patch releases do not reset the support clock.
- There will always be a supported upgrade path from one version to any other subsequent version. By clearly defining what that upgrade path is, users can be more certain of a successful upgrade and developers will know exactly which upgrade paths must be tested. Refer to the Upgrade Policy for full details.
- We take security very seriously and we have a special team, the JSST, who review all reported issues and take the necessary action to mitigate or fix each confirmed issue. Refer to Security Policy for further information.
- We welcome contributions, individual, collaborative or corporate, that will enhance our products for the benefit of the community. Refer to our Contributor Policy for full details.
Our mission is to provide a flexible platform for digital publishing and collaboration.
To offer a stable and reliable platform for our current and future user base.
To make innovation available to users and developers on a manageable basis.
To make it easy for developers to contribute code to the project at any time.
Joomla tries to follow the slogan “power through simplicity” for all its developments. For this, we have five major principles inherent to the Joomla development strategy aimed at achieving our goals:
1.4.1 Stable master branches
It is critical to our mission that the master branch of each major version of a Joomla product is always stable and ready for a release within a short time. This is supported by our Contributor Policy.
1.4.2 Predictable, incremental software releases
1.4.3 Strong backward compatibility support
1.4.4 Sound security policy
This is supported by our Security Policy.
1.4.5 Open development process
Our development process is designed to be open and accessible for anyone who wishes to participate. We strive to create an environment where people work together to solve problems and bring innovative, fresh ideas to life in the software we produce.
The following is a summary of the minimum requirements that must be met for code contributions to be considered for inclusion in a Joomla product.
2.1 Coding standards
All code submitted for merging must comply with the latest Coding Standards.
2.2 Automated tests
Automated tests are used to isolate specific parts or features of the software and ensure that they behave correctly. All existing tests must pass before new code can be merged.
2.3 Additional tests for all new API classes and methods
Any new methods or classes added to an API must be accompanied by working unit tests to verify their correct behavior. This serves to help guarantee that not only the current code works, but that future changes do not cause an unstable master branch. Where appropriate, system tests should be created to verify expected behavior.
2.4 Documentation for all changes and additions to the code base
All classes and methods added to the code base must include thorough docblocks in the source code and explanatory text in the README.md file. Additional requirements, such as requirements for end user documentation, may be found in the CONTRIBUTING.md file.
2.5 Additional requirements for specific Joomla products
Contributions to a Joomla product such as the CMS might have additional requirements to those stated above. These could, for example, include help screens, language keys and a testable upgrade path. See the appropriate CONTRIBUTING.md for full details of any additional requirements.
The Release Policy describes how each release fits into an overall release life-cycle and defines the milestones that it must reach during that life-cycle.
3.1 Software release life-cycle
The software release life cycle is composed of distinct phases and milestones that express the software's maturity as it advances from planning to development to release and support. Not every release will go through every possible phase. For example, patch releases will generally omit the alpha, beta and release candidate milestones.
3.1.1 Planning phase
The planning phase consists mostly of discussion with little or no actual software likely to be available. An idea for a new feature may take its first tentative steps towards implementation with the publication of a Request for Comments (RFC) document on one of the developer mailing lists. An RFC is a discussion of an idea and its potential implementation with an invitation for the wider community to get involved in further discussion, feedback and refinement of the idea.
During the planning phase some code snippets or proof-of-concept implementations may be produced to demonstrate feasibility or to elicit further feedback and assessment of the idea.
Releases made during this phase are sometimes referred to as “pre-alpha” releases.
3.1.2 Development and testing phase
During this phase software is being actively written, tested and documented according to the plan. This may be coordinated by a Production Working Group, particularly for the larger features, although it might also be an individual or small group effort with no project coordination.
During this phase releases will be made that are labelled “alpha”, “beta” and “release candidate”.
Although releases made during this phase may carry version numbers, these are subject to change up until the software enters the release phase.
3.1.3 Release phase
Software enters the release phase when the first "general availability" release becomes available. In this phase the code is considered to be of production quality and suitable for use by general users.
Releases during this phase are subject to the version numbering scheme which mandates semantic versioning as explained in 3.3 Version numbering.
3.2 Software milestones
There are four milestones in the Joomla Release Life Cycle: alpha, beta, release candidate, and general availability.
The alpha milestone signifies that there is new technology in the software that is ready for testing, but that the software is not feature complete. Alpha software may also be used to demonstrate a possible combination of features to see if they work together successfully. Some features may be removed in later milestones.
The target audience for an alpha release is the development community including third-party developers who may be affected by core changes or new features.
Alpha software is not suitable for production environments.
The beta milestone is considered feature complete, but is still not considered suitable for production environments. The software is intended to be tested thoroughly for regressions, security and stability problems.
Third-party extension developers should be testing their products against all beta releases and reporting any issues on the Issue Tracker. Waiting for a release candidate is too late.
3.2.3 Release Candidate (RC)
The purpose of a release candidate is to test the final packaging and release process to ensure that everything is ready for the software to move into the release phase with the first general availability release.
It is important that third-party extension developers carry out final tests on all release candidates and report any bugs immediately. However, only significant “show stopper” bugs involving core software or the included extensions will be fixed in the release candidates. Issues that only affect third-party software will not be fixed at this stage. No features will be added or removed. A final decision on version number will have been made.
Release candidates are considered complete and suitable for production environments, however they should only be deployed in production by knowledgeable people who understand the risks. A release candidate has the potential to be relabelled as a general availability release unless critical problems emerge.
3.2.4 General Availability (GA)
The general availability milestone indicates that the release is very stable and appropriate for end users.
A software release is the distribution of software code, documentation, and support materials. Each release carries a version identifier which is structured to give readers an idea of how it relates to other releases.
Joomla strictly follows Semantic Versioning (2.0.0) and this document also uses the terminology defined there.
In summary, the version identifiers for Joomla follow a three level numerical convention where the levels are defined by change significance.
- An increment in the major version identifier indicates a break in backward compatibility.
- An increment in the minor version identifier indicates the addition of new features or a significant change to existing features.
- An increment in the patch version identifier indicates that bugs have been fixed.
Support for software that the Joomla project officially distributes is subject to this Support Policy which sets out what you can expect in the way of bug and security fixes for each release of the software. In summary, only the latest minor release within a major series is supported. After at least two years of support with no further minor releases, the code may be declared end-of-life and hence unsupported.
4.1 Issue severity
All software contains bugs, but different bugs will elicit a different level of response on their discovery depending on the severity of the issue as reported. Bugs (often referred to as issues) are classified according to the following scale:
|Issues which cause software to stop functioning (eg. PHP errors) or security issues classified as Critical or High.
|Issues that seriously impede the operation of the software (eg. PHP notices, slow behaviour) or security issues classified as Moderate or Low.
|Low level bug or annoyance.
See the Security Policy for a definition of the security levels.
4.2 Support definition
When a release is supported it means that all P1 and P2 bugs and most P3 and P4 bugs will be given due consideration and subsequently addressed. Mostly this will be done by issuing a patch release, however in some cases the issue may be addressed in the next minor or major release instead.
For the CMS, whenever a new release is made there will always be a supported upgrade path. See Upgrade Policy .
Software goes through a life cycle of development, release, improvement, and support. These four steps are in a constant evolving state until the software reaches an announced EOL (end-of-life). All major versions will have a projected life cycle of 4 years or longer from its initial release date. Determining how long a major release will be supported takes into account the date of its first release, its release roadmap and the following factors.
- A major series will have an initial active development period of no less than 2 years, immediately followed by 2 years of support. Minor releases during the active development period will not affect EOL (end-of-life). (Predictable EOL)
- During the initial active development period of 2 years, a major series will have a roadmap of milestones. Near the end of the active development period, the roadmap for a major series may become an estimated calendar of future minor release dates if applicable.
- After the initial active development period, each new minor version release will reset the 2 year support clock for the major series. Minor releases after the initial active development period will affect the end-of-life date. (Estimated EOL)
- The latest minor release is the only supported version for that major series.
- Support for a minor release ends immediately when it is superseded by a new minor release in the same major series. (Example: Support for 3.3 will end as soon as 3.4 is released.)
- The Production Department Leadership will give at least 6 months notice of the estimated last minor release in a major series. This notice will be part of the roadmap as a soft target date of the final minor version release.
- A final EOL (end-of-life) announcement for a major series will occur 18 months after the last minor version for the major series has been released. At this point, you will have 6 months of support remaining until the major series is EOL and no longer supported.
4.3.1 Predictable EOL (end-of-life) for major versions
For a period of 2 years during the initial active development period, all major versions will have a predictable EOL (end-of-life) date. Minor releases during this period will not affect the end-of-life date.
4.3.2 Estimated EOL (end-of-life) for major versions
After the initial active development period of a major version, each new minor release will continue to reset a 2-year support clock. When a major version is out of its active development period, the EOL (end-of-life) date will become an estimated date. Minor releases may go on indefinitely.
Refer to a major version’s roadmap for minor version releases after the initial active development period has ended. The major version’s roadmap may help determine planned future minor releases and their time frames if applicable.
4.3.3 Announcement of EOL (end-of-life) for major versions
The EOL (end-of-life) will be published so there is at least 6 months notice that a major version will reach end-of-life. The support period may, at the discretion of the Production Department Leadership, be extended indefinitely beyond the initial minor release 2-year period. All major releases declared to be EOL (end-of-life) will no longer be maintained by the Joomla project for either stability or security issues. Unofficial support for any unsupported software may be continued by the wider community but the Joomla project is under no obligation to assist such support in any way.
4.3.4 Patch releases for a minor version
Patch releases will not reset the support clock, nor affect the projected EOL (end-of-life) date.
- Version 4.0 is released and will initially be given a support period of 2 years, plus the 2 years remaining in its initial development life cycle from its date of its release.
- 4.1 is released 2 months after 4.0. 4.0 will no longer be supported and 4.1 will become the supported version.
- The end-of-life date will not change, even if 4.1 is the only minor version released in the 2 year active development period.
- Version 4.8 is released 2 years and 10 months after the initial major version release of 4.0.
- Version 4.8 is 10 months past the initial active development cycle of 2 years.
- Version 4.8 will have support for a period of 2 years from the release of this minor version.
- Major version 4 now has a total support release life of 4 years and 10 months from its initial release to its estimated end-of-life.
Example chart of major version EOL (end-of-life) with time frames exaggerated.
|Remaining Development Life Cycle
|January 2019 (Predictable)
|January 2019 (Predictable)
|January 2019 (Predictable)
|May 2020 (Predictable)
|January 2019 (Predictable)
|September 2019 (Estimated)
|May 2020 (Predictable)
|March 2020 (Estimated)
|May 2020 (Predictable)
|August 2021 (Estimated)
4.4 Development releases
All Alpha, Beta and Release Candidate releases (defined in SemVer as "pre-releases") must always be regarded as unsupported. It is entirely possible that these releases may contain serious bugs, security issues, forwards and backwards incompatibilities, entire features that are subsequently withdrawn, and so on. There will be no supported update or migration paths from a development release to any other release.
This policy does not apply to the Joomla Framework.
The goal for upgrading from one version of a product to any subsequent version will always be to make it is as simple and painless as possible. However, since it is not realistically possible to support direct upgrades from one arbitrary version to any other arbitrary version, this policy sets out the minimal upgrade path that will be supported.
It is important to have this supported upgrade path because testing of this path should be carried out during the development of any new release and will be a requirement for acceptance of the code. Third-party extension developers should also be aware that this is the supported upgrade path so that they can ensure that their products can also be upgraded/migrated along the same path.
An upgrade becomes a migration when there are significant backward-compatibility breaks either in the code, the data or the underlying platform (eg. PHP or MySQL) that make it difficult or impossible to upgrade a site "in-place". Instead, a new site with the later software needs to be installed, possibly on a more up-to-date platform. Then the data, configuration information and possibly some software is copied across to the newer site, with any required transformations applied.
Although ideally migrations should be simple one-click affairs, they are significantly more complex due to the break in compatibility and it may be that users will need to follow a series of manual steps in order to successfully migrate a site.
In summary, the supported upgrade path is always to first upgrade to the current fully-patched minor release in the major series currently in use, followed by a migration to the latest fully-patched minor release in the next sequential major series.
5.1 Patch releases
Patch releases must be capable of being applied by an automatic process with a very high probability of success.
The supported upgrade path to the next sequential minor or major release assumes that all patches within the currently installed minor series have been applied.
5.2 Minor releases
Minor releases should be capable of being applied by a "one-click" upgrade process with a high probability of success. Since new features may have been added it is possible that a minor release will also introduce new bugs that will subsequently be addressed in patch releases. A minor release may reduce stability whereas a patch release should always increase it. Consequently, minor releases should normally be handled by a human who can run follow-up tests to ensure that the upgrade was successful.
The supported upgrade path to the next sequential minor or major release assumes that all patches for the currently installed minor release have been applied. Once the currently installed minor release has been fully patched, the site can be upgraded to the next sequential minor release. Minor releases must be applied in sequence. For example, a site currently on release 4.3 cannot be upgraded directly to 4.6 without first upgrading to 4.4 and then to 4.5. These steps can, of course, be hidden behind a user interface so that the user is unaware of them.
5.3 Major releases
The release of a new major version effectively creates a temporary fork which persists until the older branch reaches end of life. During the period when both branches are supported, the supported upgrade/migration path will be from the current fully-patched minor release in the older branch to the current fully-patched minor release in the later branch. In the event that the upgrade/migration is not to the next sequential major release then the upgrade/migration must be carried out in stages without omitting the intermediate major versions.
5.4 Example upgrade/migration path
As an example, suppose that the current fully-patched supported releases are 4.3.8, 5.6.3 and 6.3.5. Assume also that the latest patch for the 4.2 minor release was 4.2.18. We have a site on 4.2.9 which is to be migrated to the latest 6.3.5 release. Then the supported upgrade/migration path comprises the following sequence of individual upgrade/migration steps:-
1. Apply patches from 4.2.9 to 4.2.18 (the latest patch version in the current minor series).
2. Upgrade from 4.2.18 to 4.3.8 (the latest minor version in the current major series).
3. Migrate from 4.3.8 to 5.6.3 (the latest minor version in the next sequential major series).
4. Migrate from 5.6.3 to 6.3.5 (the latest minor version in the latest major series).
Note that migrations from end of life releases are not, by definition, supported. However, it is highly likely that the last supported migration path will continue to work.
The Joomla project seeks to maintain backward compatibility as long as possible and full backward compatibility can be expected within a major series. Backward compatibility may only be broken when a new major series is started.
Clean, maintainable code is important, but as time progresses the need to maintain backward compatibility makes software more complex and less maintainable. This technical debt (see, for example: http://martinfowler.com/bliki/TechnicalDebt.html) can only be relieved in the first release of a new major series.
Sometimes the best way to continue development is to drop support for some element. This process of deprecation must be handled carefully as it can lead to backward compatibility issues.
The backward compatibility policy can only apply to certain aspects of the software and it is important that these are defined so that everyone is clear can understand the limits of that promise. In general, backward compatibility applies to, where applicable:
All PHP code in the /libraries folder which is not flagged as private is considered to be part of the Joomla API and subject to backwards compatibility constraints. This may be extended to include other PHP code, such as component classes, in the future.
6.1.3 Database schemata
All database schema changes must be accompanied by a conversion script that can be executed to losslessly convert from the old schema to the new one.
6.1.4 XML schemata
Adding new entities and attributes is generally acceptable; changing or deleting them is not.
6.1.5 JSON schemata
Adding new entities is generally acceptable; changing or deleting them is not.
6.1.6 Language keys
Changing or deleting a language key is considered a backwards compatibility break. Adding new ones is not. Substantially changing the meaning associated with a language key is a compatibility break. Rephrasing something for a more accurate description or proper en-GB grammar is not.
6.1.7 Rendered markup
For the time being, rendered markup is not subject to our backwards compatibility promise. We will try not to change markup in such a way that a site might render differently, but we can't promise not to break anything at the present time. We will work on defining ways in which we might make a backwards compatibility promise for markup in the future, but we do not currently have a satisfactory consensus on a workable standard.
Any change to a URL that will give a 404 (or some other error) where it previously gave a 200 is a break in backwards compatibility. However, if the change results in a redirect to a new URL (which gives a 200) then that is acceptable.
In general, if a URL is changed then provided the new URL delivers the exact same resource rendered in the same way then that is not considered to be a break in backwards compatibility. For example, changing the order of the arguments in the query part of a URL is not considered to be a break.
Individual products may have backward compatibility constraints additional to those listed above. These will be documented in the appropriate README.md.
An element can be marked as being deprecated in a new minor release or the first release of a new major version. Advice on how to amend code that is currently using an element that is marked as deprecated MUST be added to the documentation.
Previously deprecated elements that are no longer used in the product itself MUST be removed in the first version of a new major series but MUST NOT be removed in a minor or patch release.
For example, code that is deprecated in version 10.1 will be scheduled for removal in version 11.0.0. Code that is deprecated in 11.0.0 cannot be removed until the release of version 12.0.0.
Code that is deprecated will have a @deprecated tag added to the appropriate docblock and it will be noted in the release notes.
The Production Department Leadership may elect to defer the removal of deprecated elements if deemed appropriate.
There will no doubt be occasions when a release unintentionally breaks backward compatibility. If one or more such backward compatibility regressions are found within a major series they will be fixed by making a patch release as soon as possible after their discovery.
6.4 Minimum technical requirements
The minimum technical requirements, such as PHP version, database version, etc., can only be increased for the first release of a new major version.
Downgrading a Joomla product is not supported. Changes brought about during an upgrade may be irreversible. So if you experience an issue following an upgrade, you should restore from a backup copy made immediately prior to the upgrade.
Downgrading an element that a Joomla product depends on is also not supported. For example, whilst moving the product to a new host with a lower version of the web server, the database engine, or PHP would normally be expected to work, provided the dependent element is still within the minimum requirements for the product, this cannot be guaranteed because in some cases data used by the product may depend on some property of the dependent element that cannot be reversed. For example, downgrading an encryption library would tend to be problematical.
Similarly, migrating across dependent element types is also not supported. For example, moving from Postgres to MySQL or vice versa, is not supported. There may be third-party tools available which are able to perform such a migration, but these are outside the scope of our support policy.
The team of developers and security experts tasked with implementing the Joomla Project Security Policy is the Joomla Security Strike Team (JSST). The JSST is tasked with investigating and responding to reported core vulnerabilities, executing core code reviews before software releases, providing a public presence regarding security issues, and helping the public to better understand Joomla security issues.
7.1 Security announcements
Joomla is a member of oCERT (along with a number of other security conscious software companies and organisations). Those reporting security issues may do so through oCERT or the JSST directly, but either way the JSST will make reasonable effort to work within the oCERT guidelines.
7.2 Public responses
We appreciate the efforts of people finding and reporting security issues but we encourage reporters to hold back information until Joomla releases a patched version of the software. Reporters that do so will be credited on the official vulnerability report.
The project does not disclose proof-of-concept information to demonstrate vulnerabilities and reporters are encouraged to do the same. Where a reporter feels strongly that proof-of-concept instructions should be published, they are encouraged to hold that information for an additional period of at least 4 weeks after the release of the patched version of the software.
The JSST will be available to answer questions and/or validate any Joomla security related articles at the publisher’s request.
7.3 Security releases
Unless the threat level dictates otherwise, security patches will be rolled into the next available release of the software subject to oCERT guidelines and best practice.
7.4 Vulnerability threat levels
There are two main details that contribute to a vulnerability’s priority or "threat level": impact and severity. The following tables provide generic guidelines for how vulnerabilities may be assessed. In practice each vulnerability will be assessed for damage potential and ranked accordingly.
|“0-day" attacks, and attacks where site control is compromised (allows attacker to take control over site).
|SQL injection attacks, remote file include attacks, and other attack vectors where site data is compromised.
|XSS attacks, write ACL violations (editing or creating of content where not allowed).
|Read ACL violations (reading of content where not allowed).
|VERY easy to perform. Relies on no outside information (TRUE 0-day attack).
|As soon as possible
|Moderately easy to perform. May rely on readily available outside information.
|Per oCERT guidelines
|Not easy to perform. May rely on sensitive information.
|Per oCERT guidelines
|Difficult to perform. Relies on sensitive information or requires special circumstances to perform.
|Per oCERT guidelines
Appendix A: Example life cycle
For following example is provided to help understand how it all works:
|New minor version; includes new features.
|3.3.1 to 3.3.7
|Seven patch versions fixing bugs approximately once a month; no new features.
|New features plus several bug patches merged; trigger new minor release.
|3.4.1 to 3.4.3
|Bug fix releases about two months apart.
|Critical security fix released two days after 3.4.3
|New features ready and merged; released about a month after 3.4.3
|3.5.1 to 3.5.2
|Bug fix releases.
|Team working on new features break compatibility with 3.x. triggers a major version increment; alpha process started.
|3.5.3 to 3.5.7
|Bug fix releases
|4.0.0-Beta1 to 4.0.0-Beta4
|Feature complete testing release for version 4.0
|Bug fixing continues for 3.5
|4.0.0-RC's to 4.0.0-GA
|Release candidates pass final testing and 4.0-GA is released
|Bug fix release.
|4.0.1 to 4.0.3
|The inevitable bug swarm after a new major version hit.
|New feature in the 4.x series; trigger minor version increment.
|4.1.1 to 4.1.9
|Regular bug fix releases.
|New features merged plus some bug and low priority security fixes.
|Some minor new feature released for 3.x
|4.3 to 4.7
|Many new features released over a period of time.
|Minor bug fixes; Production Department Leadership sees noticeable reduction of interest in the 3.x series; announces that the next minor release of 3.x will go onto Long Term Support
|New features for 4.x
|LTS version release; no new features; security and major bug support only.
|New features for 4.x
|3.7.1 and 4.9.1
|Security patch for vulnerability in both the 3.x and 4.x versions.
|Released 18 months after 3.7.0; support technically continues for the next six months but no issues require attention; software reaches end of life two years after the release of 3.7.0.
Document Revision History
13 March 2014 — Formally approved for adoption by the Production Leadership Team.