tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-01 13:48:37 +02:00
Code Issues Projects Releases Wiki Activity

Semver documented in release process

Browse Source 
See https://groups.google.com/forum/#!topic/silverstripe-dev/J4U4Nl2qTSg.
This commit is contained in:
Ingo Schommer 2014-12-05 10:27:52 +13:00
parent 658216237e
commit f2237aff8d
1 changed files with 24 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
docs/en/05_Contributing/02_Release_Process.md
View File

@ -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