mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-09-28 20:29:15 +02:00
DOCS Update security release docs / satis instructions (#7681)
* DOCS Update security release docs / satis instructions * Update based on testing
This commit is contained in:
Damian Mooyman
Aaron Carlino
parent
00e996f164
commit
22314de559
@ -1,5 +1,5 @@
|
||||
title: Making a SilverStripe core release
|
||||
summary: Development guide for core contributors to build and publish a new release
|
||||
summary: Development guide for core contributors to build and publish a new release
|
||||
|
||||
# Making a SilverStripe core release
|
||||
|
||||
@ -12,7 +12,7 @@ The artifacts for this process are typically:
|
||||
* A downloadable tar / zip on silverstripe.org
|
||||
* A published announcement
|
||||
* A new composer installable stable tag for silverstripe/installer
|
||||
|
||||
|
||||
While this document is not normally applicable to normal silverstripe contributors,
|
||||
it is still useful to have it available in a public location so that these users
|
||||
are aware of these processes.
|
||||
@ -29,7 +29,10 @@ As a core contributor it is necessary to have installed the following set of too
|
||||
be installed in a global location via the below command. Please see the installation
|
||||
docs on the cow repo for more setup details.
|
||||
`composer global require silverstripe/cow dev-master`
|
||||
* [transifex client](http://docs.transifex.com/client/).
|
||||
* [satis repository tool](https://github.com/composer/satis). This should be installed
|
||||
globally for minimum maintenance.
|
||||
`composer global require composer/satis ^1@dev` (or `^1@alpha` for php 5)
|
||||
* [transifex client](http://docs.transifex.com/client/).
|
||||
`pip install transifex-client`
|
||||
If you're on OSX 10.10+, the standard Python installer is locked down.
|
||||
Use `brew install python; sudo easy_install pip` instead
|
||||
@ -94,7 +97,7 @@ When doing a security release, typically one or more (or sometimes all) of the b
|
||||
steps will need to be performed manually. As such, this guide should not be followed
|
||||
exactly the same for these.
|
||||
|
||||
Standard practice is to produce a pre-release for any patched modules on the security
|
||||
Standard practice is to produce a pre-release for any patched modules on the security
|
||||
forks for cms and framework (see [silverstripe-security](https://github.com/silverstripe-security)).
|
||||
|
||||
<div class="warning" markdown="1">
|
||||
@ -118,14 +121,18 @@ Producing a security fix follows this general process:
|
||||
release date of the final stable is not known, then it's ok to give an estimated
|
||||
release schedule.
|
||||
* Push the current upstream target branches (e.g. 3.2) to the corresponding security fork
|
||||
to a new branch named for the target release (e.g. 3.2.4). Security fixes should be
|
||||
applied to this branch only. Once a fix (or fixes) have been applied to this branch, then
|
||||
a tag can be applied, and a private release can then be developed in order
|
||||
to test this release.
|
||||
to the equivalent branch on [silverstripe-security](https://github.com/silverstripe-security).
|
||||
Security fixes should be applied to the branch on this private repository only.
|
||||
Once a fix (or fixes) have been applied to this branch, then a tag can be applied,
|
||||
and a private release can then be developed in order to test this release.
|
||||
* Once upstream branches are all pushed to the security forks, make sure to merge all
|
||||
security fixes into those branches prior to running cow.
|
||||
* Setup a temporary [satis](https://github.com/composer/satis) repository which points to all relevant repositories
|
||||
containing security fixes. See below for setting up a temporary satis repository.
|
||||
* Once release testing is completed and the release is ready for stabilisation, then these fixes
|
||||
can then be pushed to the upstream module fork, and the release completed as per normal.
|
||||
Make sure to publish any draft security pages at the same time as the release is published (same day).
|
||||
* After the final release has been published, close related JIRA issues
|
||||
* After the final release has been published, close related JIRA issues
|
||||
at [open source security jira](https://silverstripe.atlassian.net/secure/RapidBoard.jspa?rapidView=198&view=detail)
|
||||
|
||||
<div class="warning" markdown="1">
|
||||
@ -134,9 +141,62 @@ a public stable, not an RC or dev-branch. Security warnings that do not require
|
||||
can be published as soon as a workaround or usable resolution exists.
|
||||
</div>
|
||||
|
||||
### Setting up satis for hosting private security releases
|
||||
|
||||
When installing a project from protected repositories, it's necessary prior to creating your project
|
||||
to override the public repository URLs with the private repositories containing undisclosed fixes. For
|
||||
this we use [satis](https://github.com/composer/satis).
|
||||
|
||||
To setup a Satis project for a release:
|
||||
|
||||
* Ensure Satis is installed globally: `composer global require composer/satis ^1@dev` (or `^1@alpha` if you
|
||||
are running php 5)
|
||||
* `cd ~/Sites/` (or whereever your web-root is located)
|
||||
* `mkdir satis-security && cd satis-security` (or some directory specific to your release)
|
||||
* Create a config file (e.g. config.json) of the given format (add only those repositories necessary).
|
||||
|
||||
Note:
|
||||
- The homepage path should match the eventual location of the package content
|
||||
- You should add the root repository (silverstripe/installer) to ensure
|
||||
`create-project` works (even if not a private security fork).
|
||||
- You should add some package version constraints to prevent having to parse
|
||||
all legacy tags and all branches.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "SilverStripe Security Repository",
|
||||
"homepage": "http://localhost/satis-security/public",
|
||||
"repositories": {
|
||||
"installer": {
|
||||
"type": "vcs",
|
||||
"url": "https://github.com/silverstripe/silverstripe-installer.git"
|
||||
},
|
||||
"framework": {
|
||||
"type": "vcs",
|
||||
"url": "https://github.com/silverstripe-security/silverstripe-framework.git"
|
||||
}
|
||||
},
|
||||
"require": {
|
||||
"silverstripe/installer": "^3.5 || ^4",
|
||||
"silverstripe/framework": "^3.5 || ^4"
|
||||
},
|
||||
"require-all": true
|
||||
}
|
||||
```
|
||||
|
||||
* Build the repository:
|
||||
`satis build config.json ./public`
|
||||
* Test you can view the satis home page at `http://localhost/satis-security/public/`
|
||||
* When performing the release ensure you use `--repository=http://localhost/satis-security/public` (below)
|
||||
|
||||
<div class="warning" markdown="1">
|
||||
It's important that you re-run `satis build` step after EVERY change that is pushed upstream; E.g. between
|
||||
each release, if making multiple releases.
|
||||
</div>
|
||||
|
||||
## Standard release process
|
||||
|
||||
The release process, at a high level, involves creating a release, publishing it, and
|
||||
The release process, at a high level, involves creating a release, publishing it, and
|
||||
reviewing the need for either another pre-release or a final stable tag within a short period
|
||||
(normally within 3-5 business days).
|
||||
|
||||
@ -157,9 +217,9 @@ cross-posted to other relevant channels such as Twitter and Facebook.
|
||||
Sending an email to [marketing@silverstripe.com](mailto:marketing@silverstripe.com)
|
||||
with an overview of the release and a rough release timeline.
|
||||
|
||||
Check all tickets ([framework](https://github.com/silverstripe/silverstripe-framework/milestones),
|
||||
[cms](https://github.com/silverstripe/silverstripe-cms/milestones),
|
||||
[installer](https://github.com/silverstripe/silverstripe-installer/milestones)) assigned to that milestone are
|
||||
Check all tickets ([framework](https://github.com/silverstripe/silverstripe-framework/milestones),
|
||||
[cms](https://github.com/silverstripe/silverstripe-cms/milestones),
|
||||
[installer](https://github.com/silverstripe/silverstripe-installer/milestones)) assigned to that milestone are
|
||||
either closed or reassigned to another milestone.
|
||||
|
||||
Merge up from other older supported release branches (e.g. merge `3.1`->`3.2`, `3.2`->`3.3`, `3.3`->`3`, `3`->`master`).
|
||||
@ -170,13 +230,29 @@ any mistakes migrating their way into the public sphere).
|
||||
|
||||
Invoked by running `cow release` in the format as below:
|
||||
|
||||
```
|
||||
cow release <version> -vvv
|
||||
```
|
||||
`cow release <version> -vvv`
|
||||
|
||||
This command has the following parameters:
|
||||
E.g.
|
||||
|
||||
* `<version>` The version that is to be released. E.g. 3.2.4 or 4.0.0-alpha4
|
||||
`cow release 4.0.1 -vvv`
|
||||
|
||||
* `<version>` is mandatory and must be the exact tag name to release including rc/alpha/beta if applicable.
|
||||
|
||||
This command has these options (note that --repository option is critical for security releases):
|
||||
|
||||
* `-vvv` to ensure all underlying commands are echoed
|
||||
* `--directory <directory>` to specify the folder to create or look for this project in. If you don't specify this,
|
||||
it will install to the path specified by `./release-<version>` in the current directory.
|
||||
* `--repository <repository>` will allow a custom composer package url to be specified. E.g. `http://packages.cwp.govt.nz`
|
||||
See the above section "Setting up satis for hosting private security releases" on how to prepare a custom
|
||||
repository for a security release.
|
||||
* `--branching <type>` will specify a branching strategy. This allows these options:
|
||||
* `auto` - Default option, will branch to the minor version (e.g. 1.1) unless doing a non-stable tag (e.g. rc1)
|
||||
* `major` - Branch all repos to the major version (e.g. 1) unless already on a more-specific minor version.
|
||||
* `minor` - Branch all repos to the minor semver branch (e.g. 1.1)
|
||||
* `none` - Release from the current branch and do no branching.
|
||||
* `--skip-tests` to skip tests
|
||||
* `--skip-i18n` to skip updating localisations
|
||||
|
||||
This can take between 5-15 minutes, and will invoke the following steps,
|
||||
each of which can also be run in isolation (in case the process stalls
|
||||
@ -189,14 +265,16 @@ and needs to be manually advanced):
|
||||
know to install dev-master, and installing 3.3.0 will install from 3.x-dev.
|
||||
If installing pre-release versions for stabilisation, it will use the correct
|
||||
temporary release branch.
|
||||
* `release:branch` If release:create installed from a non-rc branch, it will
|
||||
create the new temporary release branch (via `--branch-auto`). You can also customise this branch
|
||||
with `--branch=<branchname>`, but it's best to use the standard.
|
||||
* `release:plan` The release plan will be auto-generated, and presented on the screen
|
||||
for the user to modify or confirm. At this stage you can also modify the branching
|
||||
behaviour to be performed in the next step.
|
||||
* `release:branch` This will branch all released modules to the correct branch, if necessary.
|
||||
E.g. branching 3.7 from 3 branch in order to create the new minor version.
|
||||
* `release:translate` All upstream transifex strings will be pulled into the
|
||||
local master strings, and then the [i18nTextCollector](api:SilverStripe\i18n\TextCollection\i18nTextCollector) task will be invoked
|
||||
and will merge these strings together, before pushing all new master strings
|
||||
back up to transifex to make them available for translation. Changes to these
|
||||
files will also be automatically committed to git.
|
||||
local master strings, and then the [i18nTextCollector](api:SilverStripe\i18n\TextCollection\i18nTextCollector)
|
||||
task will be invoked and will merge these strings together, before pushing all
|
||||
new master strings back up to transifex to make them available for translation.
|
||||
Changes to these files will also be automatically committed to git.
|
||||
* `release:test` Will run all unit tests on this release. Make sure that you
|
||||
setup your `.env` correctly (as above) so that this will work.
|
||||
* `release:changelog` Will compare the current branch head with `--from` parameter
|
||||
@ -242,9 +320,24 @@ building an archive, and uploading to
|
||||
|
||||
Invoked by running `cow release:publish` in the format as below:
|
||||
|
||||
```
|
||||
cow release:publish <version> -vvv
|
||||
```
|
||||
`cow release:publish <version> -vvv`
|
||||
|
||||
E.g.
|
||||
|
||||
`cow release:publish 4.0.1`
|
||||
|
||||
This command has these options:
|
||||
|
||||
* `-vvv` to ensure all underlying commands are echoed
|
||||
* `--directory <directory>` to specify the folder to look for the project created in the prior step. As with
|
||||
above, it will be guessed if omitted. You can run this command in the `./release-<version>` directory and
|
||||
omit this option.
|
||||
* `--aws-profile <profile>` to specify the AWS profile name for uploading releases to s3. Check with
|
||||
damian@silverstripe.com if you don't have an AWS key setup.
|
||||
* `--skip-archive-upload` to disable both "archive" and "upload". This is useful if doing a private release and
|
||||
you don't want to upload this file to AWS.
|
||||
* `--skip-upload` to disable the "upload" command (but not archive)
|
||||
|
||||
As with the `cow release` command, this step is broken down into the following
|
||||
subtasks which are invoked in sequence:
|
||||
|
||||
@ -257,7 +350,7 @@ subtasks which are invoked in sequence:
|
||||
If the tags generated in the prior step are not yet available on packagist (which can
|
||||
take a few minutes at times) then this task will cycle through a retry-cycle,
|
||||
which will re-attempt the archive creation periodically until these tags are available.
|
||||
* `release:upload` This will invoke the AWS CLI command to upload these archives to the
|
||||
* `release:upload` This will invoke the AWS CLI command to upload these archives to the
|
||||
s3 bucket `silverstripe-ssorg-releases`. If you have setup your AWS profile
|
||||
for silverstripe releases under a non-default name, you can specify this profile
|
||||
on the command line with the `--aws-profile=<profile>` command.
|
||||
@ -271,9 +364,9 @@ aren't strictly able to be automated:
|
||||
source branch (e.g. merge 3.2.4 into 3.2), or sometimes create new branches if
|
||||
releasing a new minor version, and bumping up the branch-alias in composer.json.
|
||||
E.g. branching 3.3 from 3, and aliasing 3 as 3.4.x-dev. You can then delete
|
||||
the temporary release branches. This will need to be done before updating the
|
||||
the temporary release branches. This will need to be done before updating the
|
||||
release documentation in stage 3.
|
||||
* Merging up the changes in this release to newer branches, following the
|
||||
* Merging up the changes in this release to newer branches, following the
|
||||
SemVer pattern (e.g. 3.2.4 > 3.2 > 3.3 > 3 > master). The more often this is
|
||||
done the easier it is, but this can sometimes be left for when you have
|
||||
more free time. Branches not receiving regular stable versions anymore (e.g.
|
||||
@ -282,7 +375,7 @@ aren't strictly able to be automated:
|
||||
minor versions. It may be necessary to re-assign any issues assigned to the prior
|
||||
milestones to these new ones.
|
||||
* Make sure that the [releases page](https://github.com/silverstripe/silverstripe-installer/releases)
|
||||
on github shows the new tag.
|
||||
on github shows the new tag.
|
||||
|
||||
*Updating non-patch versions*
|
||||
|
||||
@ -329,7 +422,7 @@ Running either of these tasks may time out when requested, but will continue to
|
||||
only the search index rebuild takes a long period of time.
|
||||
|
||||
Note that markdown is automatically updated daily, and this should only be done if an immediate refresh is necessary.
|
||||
|
||||
|
||||
### Stage 3: Let the world know
|
||||
|
||||
Once a release has been published there are a few places where user documentation
|
||||
@ -337,7 +430,7 @@ will need to be regularly updated.
|
||||
|
||||
* Make sure that the [download page](http://www.silverstripe.org/download) on
|
||||
silverstripe.org has the release available. If it's a stable, it will appear
|
||||
at the top of the page. If it's a pre-release, it will be available under the
|
||||
at the top of the page. If it's a pre-release, it will be available under the
|
||||
[development builds](http://www.silverstripe.org/download#download-releases)
|
||||
section. If it's not available, you might need to check that the release was
|
||||
properly uploaded to aws s3, or that you aren't viewing a cached version of
|
||||
|
||||
Loading…
Reference in New Issue
Block a user