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

Merge pull request #8361 from open-sausages/pulls/4/release-docs

Browse Source 
Release process docs
This commit is contained in:
Ingo Schommer 2018-09-17 13:55:53 +12:00 committed by GitHub
commit 605ea158e8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 39 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
docs/en/05_Contributing/01_Code.md
View File

@ -76,34 +76,15 @@ there are any problems they will follow up with you, so please ensure they have
### Picking the right version
SilverStripe core and module releases (since the 3.1.8 release) follow the [Semantic Versioning](http://semver.org)
(SemVer) specification for releases. Using this specification declares to the entire development community the severity
and intention of each release. It gives developers the ability to safely declare their dependencies and understand the
scope involved in each upgrade.
The SilverStripe project follows the [Semantic Versioning](http://semver.org) (SemVer) specification for releases.
It clarifies what to expect from different releases, and also guides you in choosing the right branch
to base your pull request on. In short, most pull requests should be based on the "default branch"
which gets automatically chosen when creating a new pull request. This ensures your code
gets into the next minor release of the current major release.
Each release is labeled in the format `$MAJOR`.`$MINOR`.`$PATCH`. For example, 3.1.8 or 3.2.0.
* `$MAJOR` version is incremented if any backwards incompatible changes are introduced to the public API.
* `$MINOR` version is incremented if new, backwards compatible **functionality** is introduced to the public API or
improvements are introduced within the private code.
* `$PATCH` version is incremented if only backwards compatible **bug fixes** are introduced. A bug fix is defined as
an internal change that fixes incorrect behavior.
**Public API** refers to any aspect of the system that has been designed to be used by SilverStripe modules & site developers. In SilverStripe 3, because we haven't been clear, in principle we have to treat every public or protected method as *potentially* part of the public API, but sometimes it comes to a judgement call about how likely it is that a given method will have been used in a particular way. If we were strict about never changing publicly exposed behaviour, it would be difficult to fix any bug whatsoever, which isn't in the interests of our user community.
In future major releases of SilverStripe, we will endeavour to be more explicit about documenting the public API.
**Contributing bug fixes**
Bug fixes should be raised against the most recent MINOR release branch. For example, If your project is on 3.3.1 and 3.4.0 is released, please raise your bugfix against the `3.4` branch. Older MINOR release branches are primarily intended for critical bugfixes and security issues.
**Contributing features**
When contributing a backwards compatible change, raise it against the same MAJOR branch as your project. For example, if your project is on 3.3.1, raise it against the `3` branch. It will be included in the next MINOR release, e.g. 3.4.0. And then when it is released, you should upgrade your project to use it. As it is a MINOR change, it shouldn't break anything, and be a relatively painless upgrade.
**Contributing backwards-incompatible public API changes, and removing or radically changing existing feautres**
When contributing a backwards incompatible change, you must raise it against the `master` branch.
If you are changing existing APIs, introducing new APIs or major new features,
please review our guidance on [supported versions](release-process#supported-versions).
You will need to change the branch for your pull request accordingly.
### The Pull Request Process
@ -131,17 +112,21 @@ The current GitHub labels are grouped into five sections:
| change/major | A change for the next major release (eg: 4.0) |
| change/minor | A change for the next minor release (eg: 3.x) |
| change/patch | A change for the next patch release (eg: 3.1.x) |
| impact/critical | Broken functionality for which no work around can be produced |
| impact/high | Broken functionality but can be mitigated by other non-core code changes |
| impact/medium | Unexpected behaviour but does not break functionality |
| impact/critical | Broken functionality without workarounds, affecting major usage flows. Should target all [supported minor releases](release-process#supported-versions) |
| impact/high | Broken functionality with workarounds available, affecting major usage flows |
| impact/medium | Unexpected behaviour, or broken functionality on less common usage flows |
| impact/low | A nuisance but doesn't break any functionality (typos, etc) |
| effort/easy | Someone with limited SilverStripe experience could resolve |
| effort/medium | Someone with a good understanding of SilverStripe could resolve |
| effort/hard | Only an expert with SilverStripe could resolve |
| type/docs | A docs change |
| type/frontend | A change to front-end (CSS, HTML, etc) |
| type/ux | User experience impact |
| feedback-required/core-team | Core team members need to give an in-depth consideration |
| feedback-required/author | This issue is awaiting feedback from the original author of the PR |
| rfc/draft | [RFC](request-for-comment) under discussion |
| rfc/accepted | [RFC](request-for-comment) where agreement has been reached |
| affects/* | Issue has been observed on a specific release line |
### Quickfire Do's and Don't's

31
docs/en/05_Contributing/04_Release_Process.md
View File

@ -31,18 +31,27 @@ announced on the ["releases" forum category](https://forum.silverstripe.org/c/re
SilverStripe follows [Semantic Versioning](http://semver.org).
## Supported versions
## Supported versions {#supported-versions}
Our version support is outlined on [silverstripe.org/roadmap](http://silverstripe.org/roadmap).
At any point in time, the core development team will support a set of releases to varying levels:
* The current *master* will get new features, bug fixes and API changes that might require major refactoring before going
into a release. At the moment, bugfixing and feature development might happen on the current major release branch (e.g. *4*), to be
merged forward to master regularly.
* Applicable bugfixes on master will also be merged back to the last major release branch, to be released as the next
patch release
* Security fixes will be applied to the current master,
as well as patch releases for SilverStripe versions in "active development", "full support" or "limited support".
* The status of major releases is determined by the [roadmap](http://silverstripe.org/roadmap)
* Minor releases of major releases in "active development" or "full support" are released roughly every three months, and their End-of-Life (EOL) is announced at least six months in advance
* The latest minor release is supported as long as the underlying major release
* API changes and major new features are applied to the master branch, to be included in the next major release
* New APIs can be applied to the current minor release of major releases in "active development", but should usually be marked as "internal" APIs until they're considered stable
* Enhancements are applied to the next minor release of major releases in "active development"
* Non-critical bugfixes are applied to all supported minor releases of major releases in "active development" or "full support"
* Critical bugfixes and security fixes are applied to the all minor releases of major releases in "active development", "full support" or "limited support"
* Any patches applied to older minor releases are merged up regularly to newer minor releases (in the same major release)
* Any patches applied to older major releases are merged up regularly to newer major releases
Note that this only applies to the "core" recipe
(the modules included by [silverstripe/recipe-core](https://github.com/silverstripe/recipe-core)
and [silverstripe/recipe-cms](https://github.com/silverstripe/recipe-cms)).
For [supported modules](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/) outside of this recipe,
please refer to our [supported modules definition](https://www.silverstripe.org/software/addons/supported-modules-definition/).
## Deprecation
@ -162,15 +171,19 @@ Follow these instructions in sequence as much as possible:
* Create a draft page under [Open Source > Download > Security Releases](https://www.silverstripe.org/admin/pages/edit/show/794) on silverstripe.org. Describe the issue in a readable way, make the impact clear. Credit the author if applicable.
* Clarify who picks up owns the issue resolution
* When developing a fix:
* Ensure you're working on the oldest supported minor release branch of every supported major release (see [Supported Versions](#supported-versions))
* Move the issue into "In Progress" on the [project board](https://github.com/silverstripe-security/security-issues/projects/1)
* Add fixes on the [http://github.com/silverstripe-security](http://github.com/silverstripe-security) repo
* Ensure that all security commit messages are prefixed with the CVE. E.g. "[ss-2015-001] Fixed invalid XSS"
* Get them peer reviewed by posting on security@silverstripe.org with a link to the Github issue
* Before release (or release candidate)
* Merge back from [http://github.com/silverstripe-security](http://github.com/silverstripe-security) repos shortly at the release (minimise early disclosure through source code)
* Merge up to newer minor release branches (see [Supported Versions](#supported-versions))
* Send out a note on the pre-announce list with a highlevel description of the issue and impact (usually a copy of the yet unpublished security release page on silverstripe.org)
* Link to silverstripe.org security release page in the changelog.
* Move the issue to "Awaiting Release" in the [project board](https://github.com/silverstripe-security/security-issues/projects/1)
* Perform release
* Follow the steps for [making a core release](making-a-silverstripe-core-release)
* After release
* Publish silverstripe.org security release page
* Respond to issue reporter with reference to the release on the same discussion thread (cc security@silverstripe.org)

4
docs/en/05_Contributing/05_Making_A_SilverStripe_Core_Release.md
View File

@ -23,7 +23,7 @@ As a core contributor it is necessary to have installed the following set of too
### First time setup: Standard releases
* PHP 5.3+ (for SilverStripe 3.x) or PHP 5.6+ (for SilverStripe 4.x)
* PHP 5.6+
* Python 2.7 / 3.5
* [cow release tool](https://github.com/silverstripe/cow#install). This should typically
be installed in a global location via the below command. Please see the installation
@ -161,7 +161,7 @@ Check all tickets assigned to that milestone are either closed or reassigned to
Use the [list of all issues across modules](https://www.silverstripe.org/community/contributing-to-silverstripe/github-all-core-issues)
as a starting point, and add a `milestone:"your-milestone"` filter.
Merge up from other older supported release branches (e.g. merge `3.1`->`3.2`, `3.2`->`3.3`, `3.3`->`3`, `3`->`master`).
Merge up from other older [supported release branches](release-process#supported-versions) (e.g. merge `3.1`->`3.2`, `3.2`->`3.3`, `3.3`->`3`, `3`->`master`).
This is the part of the release that prepares and tests everything locally, but
doe not make any upstream changes (so it's safe to run without worrying about