Permalink
Browse files

docs(releases): Clarify BC policy for major releases

Fixes #7080
  • Loading branch information...
ewinslow committed Jul 19, 2015
1 parent ab6b2b5 commit a636bf8610e26e45e8960af3600dcebe16e135b9
Showing with 46 additions and 21 deletions.
  1. +46 −21 docs/appendix/releases.rst
View
@@ -3,49 +3,74 @@ Release Policy
What to expect when upgrading Elgg.
In general, we adhere to `semantic versioning`_.
We adhere to `semantic versioning`_.
.. _semantic versioning: http://semver.org
Follow the blog to `stay up to date on the latest releases`__.
__ https://community.elgg.org/blog/all
Bugfix Releases (1.9.x)
-----------------------
Patch/Bugfix Releases (1.9.x)
-----------------------------
Every few weeks.
Bugfix releases are made regularly to make sure Elgg stays stable, secure, and bug-free.
The higher the third digit, the more tested and stable the release is.
Since bugfix release focus on fixing bugs and not making major changes,
themes and plugins should work from bugfix release to bugfix release.
Feature Releases (1.x.0)
------------------------
Minor/Feature Releases (1.x.0)
------------------------------
Every few months.
New features are introduced in Elgg every few months in minor new feature releases.
These versions are identified by the second digit (1.**8**.0).
Whenever we introduce new features, we'll bump the middle version number.
These releases aren't as mature as bugfix release, but are considered stable and useable.
Though these releases try to be backward compatible,
features are added, unused code removed, and overall improvements are made,
so plugins and themes might need to be updated to make use of the new and improved features.
We make every effort to be backward compatible in these releases,
so plugins should work from minor release to minor release.
However, plugins might need to be updated to make use of the new features.
Major Releases (x.0.0)
----------------------
Major/Breaking Releases (x.0.0)
-------------------------------
Every few years.
Elgg, as all software, inevitably undergoes serious changes and a major new feature release is made.
These releases are opportunities for the core team to make dramatic improvements to the underlying platform.
Inevitably, improving Elgg requires breaking changes and a new major release is made.
These releases are opportunities for the core team to make strategic, breaking changes to the underlying platform.
Themes and plugins from older versions are not expected to work without modification on different major releases.
We may remove deprecated APIs, but we will not remove APIs without first deprecating them.
Elgg's dependencies may be upgraded by their major version or removed entirely.
We will not remove any dependences before a major release, but we do not "deprecate"
dependencies or issue any warnings before removing them.
Your package, plugin, or app should declare its own dependencies directly so that
this does not cause a problem.
Alphas, Betas, and Release Candidates
-------------------------------------
Before major releases (and sometimes before feature releases), the core team will
offer a pre-release version of Elgg to get some real-world testing and feedback
on the release. These are meant for testing only and should not be used on a live
site.
SemVer 2.0 does not define a particular meaning for pre-releases, but we approach
alpha, beta, and rc releases with these general guidelines:
An ``-alpha.X`` pre-release means that there are still breaking changes planned,
but the feature set of the release is frozen. No new features or breaking changes
can be proposed for that release.
A ``-beta.X`` pre-release means that there are no known breaking changes left to
be included, but there are known regressions or critical bugs left to fix.
An ``-rc.X`` pre-release means that there are no known regressions or critical
bugs left to be fixed. This version could become the final stable version of
Elgg if no new blockers are reported.
Release Candidates/Betas
------------------------
Before feature releases and major releases, the core team will typically offer a release candidate or beta.
These are meant for testing only and should not be considered production quality.
The core team makes these releases available to get some real-world testing and feedback on the release.
That said, the API in release candidates is considered stable, so
once a release candidate is made available, you should feel comfortable writing plugins against any new APIs.

0 comments on commit a636bf8

Please sign in to comment.