mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 12:05:37 +00:00
Semver documented in release process
See https://groups.google.com/forum/#!topic/silverstripe-dev/J4U4Nl2qTSg.
This commit is contained in:
parent
1f7e627a50
commit
7e44cc7c3a
@ -11,78 +11,34 @@ The current maintainer responsible for planning and performing releases is Ingo
|
|||||||
## Release Planning
|
## Release Planning
|
||||||
|
|
||||||
Our most up-to-date release plans are typically in the ["framework" milestone](https://github.com/silverstripe/silverstripe-framework/issues/milestones) and ["cms" milestone](https://github.com/silverstripe/silverstripe-cms/issues/milestones).
|
Our most up-to-date release plans are typically in the ["framework" milestone](https://github.com/silverstripe/silverstripe-framework/issues/milestones) and ["cms" milestone](https://github.com/silverstripe/silverstripe-cms/issues/milestones).
|
||||||
New features and API changes are typically discussed on the [core
|
New features and API changes are discussed on the [core mailinglist](http://groups.google.com/group/silverstripe-dev). They are prioritised by the core team as tickets on
|
||||||
mailinglist](http://groups.google.com/group/silverstripe-dev). They are prioritized by the core team as tickets on
|
github.com. In addition, we collect community feedback on [silverstripe.uservoice.com](https://silverstripe.uservoice.com).
|
||||||
github.com.
|
Any feature ideas we're planning to implement will be flagged there.
|
||||||
|
|
||||||
Release dates are usually not published prior to the release, but you can get a good idea of the release status by
|
Release dates are usually not published prior to the release, but you can get a good idea of the release status by
|
||||||
reviewing the release milestone on github.com. Releases will be
|
reviewing the release milestone on github.com. Releases will be
|
||||||
announced on the [release announcements mailing list](http://groups.google.com/group/silverstripe-announce).
|
announced on the [release announcements mailing list](http://groups.google.com/group/silverstripe-announce).
|
||||||
|
|
||||||
Releases of the *cms* and *framework* modules are coupled at the moment, they
|
Releases of the *cms* and *framework* modules are coupled at the moment, they follow the same numbering scheme.
|
||||||
follow the same numbering scheme.
|
|
||||||
|
|
||||||
## Release Numbering
|
## Release Numbering
|
||||||
|
|
||||||
* Versions are numbered by major version number, minor version number, and micro version number, in the form *A.B.C*
|
SilverStripe follows [Semantic Versioning](http://semver.org).
|
||||||
(e.g. *2.4.1*)
|
|
||||||
* *A* is the *major version number*, which is only incremented for major changes and core rewrites, lots of them won't
|
|
||||||
be backwards compatible.
|
|
||||||
* *B* is the *minor version number*. It is incremented for our typical releases with new features and bugfixes. We
|
|
||||||
strive for few changes to be backwards incompatible, and will deprecate any APIs before removing them.
|
|
||||||
* *C* is the *micro version number*, incremented for bugfixes, minor enhancements and security fixes. Unless
|
|
||||||
security-related, all changes will be fully backwards compatible to the minor version number.
|
|
||||||
* Major and minor releases have an *alpha* cycle, which is a preview developer release which that see major changes
|
|
||||||
until release. It is followed by a *beta* cycle, which is feature complete and used by the wider development community
|
|
||||||
for stability and regression testing. Naming convention is *A.B.C-alpha* and *A.B.C-beta*.
|
|
||||||
* Major, minor and micro releases can have one or more *release candidates (RC)*, to be used by the wider community. A
|
|
||||||
release candidate signifies that the core team thinks the release is ready without further changes. The actual release
|
|
||||||
should be a identical copy of the latest RC. Naming convention is *A.B.C-rc1* (and further increments).
|
|
||||||
* Major releases may have a *preview* cycle which is a early snapshot of the codebase for developers before
|
|
||||||
going into the *alpha* cycle. Preview releases are named *A.B.C-pr1* (and further increments).
|
|
||||||
|
|
||||||
### Major releases
|
Note: Until November 2014, the project didn't adhere to Semantic Versioning. Instead. a "minor release" in semver terminology
|
||||||
|
was treated as a "major release" in SilverStripe. For example, the *3.1.0* release contained API breaking changes, and
|
||||||
|
the *3.1.1* release contained new features rather than just bugfixes.
|
||||||
|
|
||||||
So far, major releases have happened every couple of years. Most new releases are *minor version number* or *micro
|
## Supported versions
|
||||||
version number* increments.
|
|
||||||
So far, we have had two major releases; from the *1.x* to the *2.x* line and from the *2.x* to the *3.x* line.
|
|
||||||
|
|
||||||
### Minor releases
|
|
||||||
|
|
||||||
Minor releases have happened about once every 18 months.
|
|
||||||
For example, *2.3* was released in February 2009, followed by *2.4* in May 2010.
|
|
||||||
|
|
||||||
These releases will contain new features, general enhancements and bugfixes. APIs from previous minor releases can be
|
|
||||||
*deprecated*, but will stay available for one more minor release. So, if an API is deprecated in *A.B*, it will continue
|
|
||||||
to work in *A.B+1*, and removed in *A.B+2*.
|
|
||||||
|
|
||||||
An example: Say we'd want to rename *BasicAuth::requireLogin()* to follow our coding conventions, which is
|
|
||||||
*BasicAuth::require_login()*. The method was introduced in *2.1*, we've made the change in *2.3*?
|
|
||||||
|
|
||||||
* *2.3* would've marked the method as *@deprecated*, and documents it as an *API CHANGE* in our
|
|
||||||
[changelog](/changelogs). The old method continues to work, but will throw an *E_USER_NOTICE*.
|
|
||||||
* *2.4* would've removed the method, also documenting it as an *API CHANGE*, and mentioning it in the
|
|
||||||
[upgrading](/installation/upgrading) guidelines.
|
|
||||||
|
|
||||||
Exceptions to the deprecation cycle are APIs that have been moved into their own module, and continue to work with the
|
|
||||||
new minor release. These changes can be performed in a single minor release without a deprecation period.
|
|
||||||
|
|
||||||
### Micro releases
|
|
||||||
|
|
||||||
Micro releases are issued about every two months for the latest release, typically for security reasons.
|
|
||||||
You can safely upgrade to those releases (after reading the [upgrading](/upgrading/) guidelines).
|
|
||||||
For example, *2.3.6* was released in February 2010, followed by *2.3.7* in March 2010.
|
|
||||||
|
|
||||||
### Supported versions
|
|
||||||
|
|
||||||
At any point in time, the core development team will support a set of releases to varying levels:
|
At any point in time, the core development team will support a set of releases to varying levels:
|
||||||
|
|
||||||
* The current *development trunk* will get new features and bug fixes that might require major refactoring before going
|
* The current *master* will get new features, bug fixes and API changes that might require major refactoring before going
|
||||||
into a release (Note: At the moment, bugfixing and feature development might happen on the current release branch, to be
|
into a release. At the moment, bugfixing and feature development might happen on the current major release branch (e.g. *3*), to be
|
||||||
merged back to trunk regularly).
|
merged forward to master regularly.
|
||||||
* Applicable bugfixes on trunk will also be merged back to the last minor release branch, to be released as the next
|
* Applicable bugfixes on master will also be merged back to the last major release branch, to be released as the next
|
||||||
micro release.
|
patch release
|
||||||
* Security fixes will be applied to the current trunk and the previous two minor releases (e.g. *2.3.8* and *2.4.1*).
|
* Security fixes will be applied to the current master and the previous two major releases (e.g. *4.0*, *3.2* and *3.1*).
|
||||||
|
|
||||||
## Deprecation
|
## Deprecation
|
||||||
|
|
||||||
@ -97,30 +53,32 @@ How to deprecate an API:
|
|||||||
* Add a `@deprecated` item to the docblock tag, with a `{@link <class>}` item pointing to the new API to use.
|
* Add a `@deprecated` item to the docblock tag, with a `{@link <class>}` item pointing to the new API to use.
|
||||||
* Update the deprecated code to throw a `[api:Deprecation::notice()]` error.
|
* Update the deprecated code to throw a `[api:Deprecation::notice()]` error.
|
||||||
* Both the docblock and error message should contain the **target version** where the functionality is removed.
|
* Both the docblock and error message should contain the **target version** where the functionality is removed.
|
||||||
So if you're committing the change to a 3.1 pre-release version, the target version will either be 3.2 or 4.0,
|
So if you're committing the change to a *3.1* minor release, the target version will be *4.0*.
|
||||||
depending on how disruptive the change is.
|
* Deprecations should not be committed to patch releases
|
||||||
* Deprecations should just be committed to pre-release branches, ideally before they enter the "beta" phase.
|
* Deprecations should just be committed to pre-release branches, ideally before they enter the "beta" phase.
|
||||||
If deprecations are introduced after this point, their target version needs to be increased by one.
|
If deprecations are introduced after this point, their target version needs to be increased by one.
|
||||||
* Make sure that the old deprecated function works by calling the new function - don't have duplicated code!
|
* Make sure that the old deprecated function works by calling the new function - don't have duplicated code!
|
||||||
* The commit message should contain an `API` prefix (see ["commit message format"](code#commit-messages))
|
* The commit message should contain an `API` prefix (see ["commit message format"](code#commit-messages))
|
||||||
|
* Document the change in the [changelog](/changelogs) for the next release
|
||||||
* Deprecated APIs can be removed after developers had a chance to react to the changes. As a rule of thumb, leave the
|
* Deprecated APIs can be removed after developers had a chance to react to the changes. As a rule of thumb, leave the
|
||||||
code with the deprecation warning in for at least three micro releases. Only remove code in a minor or major release.
|
code with the deprecation warning in for at least three micro releases. Only remove code in a minor or major release.
|
||||||
|
* Exceptions to the deprecation cycle are APIs that have been moved into their own module, and continue to work with the
|
||||||
|
new minor release. These changes can be performed in a single minor release without a deprecation period.
|
||||||
|
|
||||||
Here's an example for replacing `Director::isDev()` with a (theoretical) `Env::is_dev()`:
|
Here's an example for replacing `Director::isDev()` with a (theoretical) `Env::is_dev()`:
|
||||||
|
|
||||||
:::php
|
:::php
|
||||||
/**
|
/**
|
||||||
* Returns true if your are in development mode
|
* Returns true if your are in development mode
|
||||||
* @deprecated 3.1 Use {@link Env::is_dev()} instead.
|
* @deprecated 4.0 Use {@link Env::is_dev()} instead.
|
||||||
*/
|
*/
|
||||||
public function isDev() {
|
public function isDev() {
|
||||||
Deprecation::notice('3.1', 'Use Env::is_dev() instead');
|
Deprecation::notice('4.0', 'Use Env::is_dev() instead');
|
||||||
return Env::is_dev();
|
return Env::is_dev();
|
||||||
}
|
}
|
||||||
|
|
||||||
This change could be committed to a 3.1.0-alpha2 release, stays deprecated in all following minor releases
|
This change could be committed to a minor release like *3.2.0*, and stays deprecated in all following minor releases
|
||||||
(3.1.0-beta1, 3.1.0, 3.1.1), and gets removed from 3.2.0. If the change was introduced in an already
|
(e.g. *3.3.0*, *3.4.0*), until a new major release (e.g. *4.0.0*) where it gets removed from the codebase.
|
||||||
released version (e.g. 3.1.1), the target version becomes 3.2 instead.
|
|
||||||
|
|
||||||
## Security Releases
|
## Security Releases
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user