2015-12-03 22:43:46 +01:00
title: Making a SilverStripe core release
summary: Development guide for core contributors to build and publish a new release
# Making a SilverStripe core release
## Introduction
This guide is intended to be followed by core contributors, allowing them to take
the latest development branch of each of the core modules, and building a release.
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
2018-05-07 04:27:43 +02:00
2015-12-03 22:43:46 +01:00
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.
## First time setup
As a core contributor it is necessary to have installed the following set of tools:
### First time setup: Standard releases
2018-09-05 03:57:52 +02:00
* PHP 5.6+
2015-12-03 22:43:46 +01:00
* 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
docs on the cow repo for more setup details.
2017-01-17 05:28:25 +01:00
`composer global require silverstripe/cow dev-master`
* [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
2015-12-03 22:43:46 +01:00
* [AWS CLI tools ](https://aws.amazon.com/cli/ ):
2017-01-17 05:28:25 +01:00
`pip install awscli`
2015-12-21 01:30:09 +01:00
* The `tar` and `zip` commands
2017-01-30 16:34:55 +01:00
* A good `.env` setup in your localhost webroot.
2015-12-03 22:43:46 +01:00
2017-01-30 16:34:55 +01:00
Example `.env` :
2017-10-27 04:38:27 +02:00
2017-08-03 02:51:32 +02:00
```
2017-10-27 04:38:27 +02:00
# Environent
SS_TRUSTED_PROXY_IPS="*"
SS_ENVIRONMENT_TYPE="dev"
# DB Credentials
SS_DATABASE_CLASS="MySQLDatabase"
SS_DATABASE_SERVER="127.0.0.1"
SS_DATABASE_USERNAME="root"
SS_DATABASE_PASSWORD=""
# Each release will have its own DB
SS_DATABASE_CHOOSE_NAME=1
# So you can test releases
SS_DEFAULT_ADMIN_USERNAME="admin"
SS_DEFAULT_ADMIN_PASSWORD="password"
# Basic CLI request url default
SS_BASE_URL="http://localhost/"
2017-08-03 02:51:32 +02:00
```
2015-12-03 22:43:46 +01:00
2018-05-07 04:27:43 +02:00
You will also need to be assigned the following permissions. Contact one of the SilverStripe staff from
2015-12-03 22:43:46 +01:00
the [core committers ](core_committers ), who will assist with setting up your credentials.
2018-05-07 04:27:43 +02:00
* Write permissions on the [silverstripe ](https://github.com/silverstripe ) organisation.
2015-12-03 22:43:46 +01:00
* Admin permissions on [transifex ](https://www.transifex.com/silverstripe/ ).
2017-01-17 05:29:11 +01:00
Set up a [~/.transifexrc ](https://docs.transifex.com/client/client-configuration ) with your credentials.
* AWS write permissions on the `silverstripe-ssorg-releases` s3 bucket
([add credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) via `aws configure` ).
2015-12-03 22:43:46 +01:00
* Permission on [silverstripe release announcement ](https://groups.google.com/forum/#!forum/silverstripe-announce ).
2017-12-18 23:45:16 +01:00
* Moderator permissions in the [Slack channel ](https://www.silverstripe.org/community/slack-signup/ )
2016-02-29 23:19:41 +01:00
* Administrator account on [docs.silverstripe.org ](https://docs.silverstripe.org ) and
[userhelp.silverstripe.org ](https://userhelp.silverstripe.org ).
2015-12-03 22:43:46 +01:00
### First time setup: Security releases
For doing security releases the following additional setup tasks are necessary:
* Write permissions on the [silverstripe-security ](https://github.com/silverstripe-security )
organisation.
* Permissions to write to the [security releases page ](http://www.silverstripe.org/download/security-releases )
2018-05-07 04:27:43 +02:00
and the [silverstripe.org CMS ](http://www.silverstripe.org/admin ).
2015-12-03 22:43:46 +01:00
* Permission on [security pre-announcement mailing list ](https://groups.google.com/a/silverstripe.com/forum/#!forum/security-preannounce ).
## Security release process
When doing a security release, typically one or more (or sometimes all) of the below
steps will need to be performed manually. As such, this guide should not be followed
exactly the same for these.
2015-12-21 01:30:36 +01:00
Standard practice is to produce a pre-release for any patched modules on the security
2018-05-07 04:27:43 +02:00
forks, e.g. for cms and framework (see [silverstripe-security ](https://github.com/silverstripe-security )).
2015-12-03 22:43:46 +01:00
< div class = "warning" markdown = "1" >
Security issues are never disclosed until a public stable release containing this fix
is available, or within a reasonable period of time of such a release.
< / div >
Producing a security fix follows this general process:
* When a security issue is disclosed on security@silverstripe.com it should be given
a CVE (common vulnerability exposure) code. E.g. ss-2015-020. Make sure you thank
anyone who disclosed this issue, and confirm with them as soon as possible whether
this issue is a verified security issue.
* Log this CVE, along with description, release version, and name of reporter in
2018-05-07 04:27:43 +02:00
the [security issues GitHub repository ](https://github.com/silverstripe-security/security-issues/issues ).
2015-12-03 22:43:46 +01:00
* Create a similar record of this issue on the [security releases page ](http://www.silverstripe.org/download/security-releases )
in draft mode.
* Post a pre-announcement to the [security pre-announcement list ](https://groups.google.com/a/silverstripe.com/forum/#!forum/security-preannounce ).
2018-05-07 04:27:43 +02:00
It's normally ideal to include a [CVSS ](https://nvd.nist.gov/CVSS-v2-Calculator )
2015-12-03 22:43:46 +01:00
(common vulnerability scoring system) along with this pre-announcement. If the
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
2015-12-21 01:30:36 +01:00
a tag can be applied, and a private release can then be developed in order
to test this release.
2016-01-04 23:27:31 +01:00
* Once release testing is completed and the release is ready for stabilisation, then these fixes
2015-12-23 04:07:25 +01:00
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).
2018-05-07 04:27:43 +02:00
* After the final release has been published, close related GitHub issues
in the [security-issues repository ](https://github.com/silverstripe-security/security-issues/issues ).
2015-12-23 04:07:25 +01:00
< div class = "warning" markdown = "1" >
Note: It's not considered acceptable to disclose any security vulnerability until a fix exists in
a public stable, not an RC or dev-branch. Security warnings that do not require a stable release
can be published as soon as a workaround or usable resolution exists.
< / div >
2015-12-03 22:43:46 +01:00
## Standard release process
2015-12-21 01:30:36 +01:00
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
2015-12-03 22:43:46 +01:00
(normally within 3-5 business days).
2015-12-21 01:30:36 +01:00
During the pre-release cycle a temporary branch is created, and should only receive
absolutely critical fixes during the cycle. Any changes to this branch should
result in the requirement for a new release, thus a higher level of scrutiny is typically
2015-12-03 22:43:46 +01:00
placed on any pull request to these branches.
2015-12-21 01:30:36 +01:00
When creating a new pre-release or stable, the following process is broken down into two
2015-12-03 22:43:46 +01:00
main sets of commands:
### Stage 1: Release preparation:
2015-12-23 04:07:25 +01:00
If you are managing a release, it's best to first make sure that SilverStripe marketing
are aware of any impending release. This is so that they can ensure that a relevant blog
post will appear on [www.silverstripe.org/blog ](http://www.silverstripe.org/blog/ ), and
2018-02-07 04:01:40 +01:00
cross-posted to other relevant channels such as social media.
Blog posts should be prepared for each major, minor and security releases.
Patch releases, alphas, betas and release candidates usually don't need blog posts,
unless they're introducing important changes (e.g. for a new major release).
2016-01-04 23:27:31 +01:00
Sending an email to [marketing@silverstripe.com ](mailto:marketing@silverstripe.com )
with an overview of the release and a rough release timeline.
2018-01-29 03:38:04 +01:00
Check all tickets assigned to that milestone are either closed or reassigned to another milestone.
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.
2016-01-04 23:27:31 +01:00
2018-09-05 03:57:40 +02:00
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`).
2015-12-23 04:07:25 +01:00
2015-12-03 22:43:46 +01:00
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
any mistakes migrating their way into the public sphere).
Invoked by running `cow release` in the format as below:
2017-10-27 04:38:27 +02:00
2017-08-03 02:51:32 +02:00
```
2017-10-27 04:38:27 +02:00
cow release < version > -vvv
2017-08-03 02:51:32 +02:00
```
2017-10-27 04:38:27 +02:00
2015-12-03 22:43:46 +01:00
This command has the following parameters:
2017-01-17 05:29:28 +01:00
* `<version>` The version that is to be released. E.g. 3.2.4 or 4.0.0-alpha4
2015-12-03 22:43:46 +01:00
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
and needs to be manually advanced):
2017-01-17 05:29:28 +01:00
* `release:create` The release version will be created in the `release-<version>`
2015-12-03 22:43:46 +01:00
folder directly underneath the folder this command was invoked in. Cow
will look at the available versions and branch-aliases of silverstripe/installer
to determine the best version to install from. E.g. installing 4.0.0 will
know to install dev-master, and installing 3.3.0 will install from 3.x-dev.
2015-12-21 01:30:36 +01:00
If installing pre-release versions for stabilisation, it will use the correct
temporary release branch.
2015-12-03 22:43:46 +01:00
* `release:branch` If release:create installed from a non-rc branch, it will
2015-12-21 01:30:36 +01:00
create the new temporary release branch (via `--branch-auto` ). You can also customise this branch
2015-12-03 22:43:46 +01:00
with `--branch=<branchname>` , but it's best to use the standard.
* `release:translate` All upstream transifex strings will be pulled into the
2017-07-03 03:22:12 +02:00
local master strings, and then the [i18nTextCollector ](api:SilverStripe\i18n\TextCollection\i18nTextCollector ) task will be invoked
2015-12-03 22:43:46 +01:00
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
2017-01-30 16:34:55 +01:00
setup your `.env` correctly (as above) so that this will work.
2015-12-03 22:43:46 +01:00
* `release:changelog` Will compare the current branch head with `--from` parameter
version in order to generate a changelog file. This wil be placed into the
`./framework/docs/en/04_Changelogs/` folder. If an existing file named after
this version is already in that location, then the changes will be automatically
regenerated beneath the automatically added line:
`<!--- Changes below this line will be automatically regenerated -->` .
It may be necessary to edit this file to add details of any upgrading notes
or special considerations. If this is a security release, make sure that any
links to the security registrar (http://www.silverstripe.org/download/security-releases)
match the pages saved in draft.
Once the release task has completed, it may be ideal to manually test the site out
by running it locally (e.g. `http://localhost/release-3.3.4` ) to do some smoke-testing
and make sure that there are no obvious issues missed.
2016-01-04 23:27:31 +01:00
Since `cow` will only run the unit test suite, you'll need to check
2018-01-29 03:38:04 +01:00
the build status of Behat end-to-end tests manually on travis-ci.org.
Check the badges on the various modules available on [github.com/silverstripe ](http://github.com/silverstripe ).
2016-01-04 23:27:31 +01:00
2015-12-03 22:43:46 +01:00
It's also ideal to eyeball the git changes generated by the release tool, making sure
2016-01-04 23:27:31 +01:00
that no translation strings were unintentionally lost, no malicious changes were
introduced in the (community contributed) translations, and that the changelog
2015-12-03 22:43:46 +01:00
was generated correctly.
2015-12-23 04:07:25 +01:00
In particular, double check that all necessary information is included in the release notes,
including:
* Upgrading notes
* Security fixes included
* Major changes
2015-12-03 22:43:46 +01:00
Once this has been done, then the release is ready to be published live.
### Stage 2: Release publication
Once a release has been generated, has its translations updated, changelog generated,
and tested, the next step is to publish the release. This involves tagging,
building an archive, and uploading to
[www.silverstripe.org ](http://www.silverstripe.org/software/download/ ) download page.
Invoked by running `cow release:publish` in the format as below:
2017-10-27 04:38:27 +02:00
2017-08-03 02:51:32 +02:00
```
2017-10-27 04:38:27 +02:00
cow release:publish < version > -vvv
2017-08-03 02:51:32 +02:00
```
2015-12-03 22:43:46 +01:00
As with the `cow release` command, this step is broken down into the following
subtasks which are invoked in sequence:
* `release:tag` Each module will have the appropriate tag applied (except the theme).
2015-12-21 01:30:36 +01:00
* `release:push` The temporary release branches and all tags are pushed up to origin on github.
2015-12-03 22:43:46 +01:00
* `release:archive` This will generate a new tar.gz and zip archive, each for
cms and framework-only installations. These will be copied to the root folder
of the release directory, although the actual build will be created in temporary
directories (so any temp files generated during testing will not end up in the release).
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
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.
2017-01-17 23:06:19 +01:00
See "Stage 3: Let the world know" to check if this worked correctly.
2015-12-03 22:43:46 +01:00
Once all of these commands have completed there are a couple of final tasks left that
aren't strictly able to be automated:
* If this is a stable release, it will be necessary to perform a post-release merge
2015-12-21 01:30:36 +01:00
on open source. This normally will require you to merge the temporary release branch into the
2015-12-03 22:43:46 +01:00
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
2015-12-21 01:30:36 +01:00
the temporary release branches. This will need to be done before updating the
2015-12-03 22:43:46 +01:00
release documentation in stage 3.
* 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.
3.0 or 3.1) should usually be omitted.
* Set the github milestones to completed, and create placeholders for the next
minor versions. It may be necessary to re-assign any issues assigned to the prior
2017-01-17 23:06:24 +01:00
milestones to these new ones.
2015-12-03 22:43:46 +01:00
* Make sure that the [releases page ](https://github.com/silverstripe/silverstripe-installer/releases )
2017-01-17 23:06:24 +01:00
on github shows the new tag.
2015-12-03 22:43:46 +01:00
2015-12-23 04:07:25 +01:00
*Updating non-patch versions*
If releasing a new major or minor version it may be necessary to update various SilverStripe portals. Normally a new
minor version will require a new branch option to be made available on each site menu. These sites include:
2016-02-29 23:19:41 +01:00
* [docs.silverstripe.org ](https://docs.silverstripe.org ):
* New branches (minor releases) require a code update. Changes are made to
[github ](https://github.com/silverstripe/doc.silverstripe.org ) and deployed via
[SilverStripe Platform ](https://platform.silverstripe.com/naut/project/SS-Developer-Docs/environment/Production/ )
2016-05-30 00:37:41 +02:00
* The new version needs to be added to `app/_config/docs-repositories.yml`
* Update the version for the "contributing" rewrite rule in `.htaccess` (`RewriteRule ^(.*)/(.*)/contributing/?(.*)?$ ...`)
2016-02-29 23:19:41 +01:00
* Updates to markdown only can be made via the [build tasks ](https://docs.silverstripe.org/dev/tasks ).
See below for more details.
* [userhelp.silverstripe.org ](https://userhelp.silverstripe.org/en/3.2 ):
* Updated similarly to docs.silverstripe.org: Code changes are made to
[github ](https://github.com/silverstripe/userhelp.silverstripe.org ) and deployed via
[SilverStripe Platform ](https://platform.silverstripe.com/naut/project/SS-User-Docs/environment/Production/ ).
* The content for this site is pulled from [silverstripe-userhelp-content ](https://github.com/silverstripe/silverstripe-userhelp-content )
* Updates to markdown made via the [build tasks ](https://userhelp.silverstripe.org/dev/tasks ).
See below for more details.
* [demo.silverstripe.org ](http://demo.silverstripe.org/ ): Update code on
[github ](https://github.com/silverstripe/demo.silverstripe.org/ )
and deployed via [SilverStripe Platform ](https://platform.silverstripe.com/naut/project/ss3demo/environment/live ).
2015-12-23 04:07:25 +01:00
* [api.silverstripe.org ](https://api.silverstripe.org ): Update on [github ](https://github.com/silverstripe/api.silverstripe.org )
2016-02-29 23:19:41 +01:00
and deployed via [SilverStripe Platform ](https://platform.silverstripe.com/naut/project/api/environment/live ). Currently
the only way to rebuild the api docs is via SSH in and running the apigen task.
2015-12-23 04:07:25 +01:00
2016-04-06 09:39:17 +02:00
Further manual work on major or minor releases:
* Check that `Deprecation::notification_version('4.0.0');` in framework/_config.php points to
2015-12-23 04:07:25 +01:00
the right major version. This should match the major version of the current release. E.g. all versions of 4.x
should be set to `4.0.0` .
2016-04-06 09:39:17 +02:00
* Update the [userhelp.silverstripe.org ](userhelp.silverstripe.org ) version link in `LeftAndMain.help_link`
2015-12-23 04:07:25 +01:00
2016-02-29 23:19:41 +01:00
*Updating markdown files*
When updating markdown on sites such as userhelp.silverstripe.org or docs.silverstripe.org, the process is similar:
* Run `RefreshMarkdownTask` to pull down new markdown files.
* Then `RebuildLuceneDocsIndex` to update search indexes.
Running either of these tasks may time out when requested, but will continue to run in the background. Normally
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.
2015-12-03 22:43:46 +01:00
### Stage 3: Let the world know
Once a release has been published there are a few places where user documentation
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
2015-12-21 01:30:36 +01:00
at the top of the page. If it's a pre-release, it will be available under the
2015-12-03 22:43:46 +01:00
[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
the download page. You can cache-bust this by adding `?release=<version>` to
the url. If things aren't working properly (and you have admin permissions)
you can run the [CoreReleaseUpdateTask ](http://www.silverstripe.org/dev/tasks/CoreReleaseUpdateTask )
to synchronise with packagist.
* Ensure that [docs.silverstripe.org ](http://docs.silverstripe.org ) has the
updated documentation by running the build task in the root folder. If
you do not have ssh access to this server, then contact a SilverStripe staff member
to update this for you. Make sure that the download link below links to the
correct changelog page. E.g.
[https://docs.silverstripe.org/en/3.2/changelogs/3.2.1/ ](https://docs.silverstripe.org/en/3.2/changelogs/3.2.1/ )
* Post a release announcement on the [silverstripe release announcement ](https://groups.google.com/forum/#!forum/silverstripe-announce )
google group.
2017-12-18 23:45:16 +01:00
* Update the [Slack ](https://www.silverstripe.org/community/slack-signup/ ) topic to include the new release version.
2018-02-07 04:01:40 +01:00
* For major or minor releases: Work with SilverStripe marketing to get a blog post out.
They might choose to announce the release on social media as well.
2015-12-03 22:43:46 +01:00
## See also
* [Release Process ](release_process )
* [Translation Process ](translation_process )
* [Core committers ](core_committers )
If at any time a release runs into an unsolveable problem contact the
core committers on the [discussion group ](https://groups.google.com/forum/#!forum/silverstripe-committers )
to ask for support.