Skip to content
This repository was archived by the owner on Apr 10, 2025. It is now read-only.

Release Process

Jump to bottom
Jeff Kaufman edited this page Jan 10, 2017 · 12 revisions

Overview

The release process has two components:

  1. Things that can be done anywhere (cutting the branch, writing release notes, building binaries)
  2. Things that have to be done at Google (signing the binaries, deploying them to dl.google.com)

Most of the process is in the first category, and this doc only covers that category.

We have two kinds of releases:

  1. Feature releases: cut a new branch off of master, which contains all work up to this point.
  2. Point release: patch a few small changes onto an existing branch.

For example, release 1.9.32.1 was a feature release, and all later 1.9.x.x releases (1.9.31.2 through 1.9.32.14) were point releases.

A feature release is generally a lot more work to get out, because we've made larger changes and it's more likely that something has broken that needs to be fixed before releasing. A point release, on the other hand, should be as small as possible to minimize the risk of breaking one thing while fixing another. Often this means we'll fix a bug two ways if the real fix involves a refactor: release a minimal fix for a point release, and put the larger refactor on master for the future.

Point releases are further broken down into "bugfix" and "security" releases. A bugfix release does exactly that: fixes bugs. We won't generally put one out unless there are serious bugs, but if there's a bug serious enough to be putting out a release then we'll generally backport fixes for less serious bugs to release along with it. Security releases are ones that people need to apply to avoid their site being exploited. Because we want people to apply these as quickly as possible, other fixes should go out in a separate bugfix release.

We release both beta and stable versions of mps and nps. Version x.x.x.x-beta and x.x.x.x-stable always have the same code; beta vs stable is just metadata to let sites know what they're likely to want to run. New feature releases start as beta, often have a few rounds of bugfix releases, have a few months of time for issues to crop up, and then once we have a version we think is solid we release the most recent point release as stable. For example, 1.9.32.1 was released as beta on 2014-09-16, then we made a security update to it on 2014-10-27 as 1.9.32.2 and a bug fix release on 2015-01-05 as 1.9.32.3, and then re-released 1.9.32.3 as stable on 2015-01-14.

Branching approach

For each feature release series we maintain a branch. The name (number) of the branch is the third component of the release version. For example, the 1.12.x.x series of releases is based on branch 34, and the 1.10.x.x and 1.11.x.x series were based on branch 33. When working on a release you work with the branch, and then when you have something ready to release you'll tag it.

Feature releases: cutting a branch

cd .../mod_pagespeed
git checkout master
git checkout -b NN
git push --set-upstream origin NN

cd .../ngx_pagespeed
git checkout master
git checkout -b NN
git push --set-upstream origin NN

If the current most recent branch is 34 (1.12.x.x) then you'd make a new branch and call it 35. Any changes you need to make to get this release ready should be committed to this branch.

Update VERSION

Edit net/instaweb/public/VERSION to match the expected release version. For example, change:

MAJOR=1
MINOR=13
BUILD=0
PATCH=0

to:

MAJOR=1
MINOR=13
BUILD=35
PATCH=1

Then commit:

git commit -a -m "Update VERSION for release 1.13.35.1"

Update lastchange.sh

When building from development branches mod_pagespeed reports its version as x.x.x.x-REVISION, where REVISION is the number of commits we've made on the master branch. For a release branch, however, we want it to report x.x.x.x-0:

git cherry-pick 2a4b2047

Update version on master

Builds from master always report with a minor version number one more than the current one, a branch number of 0, and a patch number of 0. For example, currently our most recent release is 1.12.34.2 so master builds report as 1.13.0.0. When you cut a feature release, update net/instaweb/public/VERSION on master to increment MINOR and zero BUILD and PATCH.

Point releases: use the existing branch

If you're making a point release, say 1.13.35.7, then first check out the branch for that release (35). Now you can cherry-pick commits onto it. For example:

cd .../mod_pagespeed
git checkout 35
git cherry-pick COMMIT-HASH
git cherry-pick OTHER-COMMIT-HASH
git push

Then update net/instaweb/public/VERSION to increment the patch number.

Release Notes

Start a draft of the release notes early: they take a surprisingly long time to get right.

The goal is to list everything that has changed between releases that users might care about. For a patch release this is simple: list the bugs fixed and the commits applied. For a feature release it's a bit more work to get a picture of what changed:

  • Look over bugs that have been marked fixed since the last release (both for nps and mps)
  • Look over pull requests that have been closed since the last release (both for nps and mps)
  • Don't look at the full diff between versions, because that's way too big, but look at diffs for files that often correspond to changes we should be noting:
    • apache/mod_instaweb.cc
    • system/system_rewrite_options.cc
    • rewriter/rewrite_filter_names.gperf
    • rewriter/rewrite_options.cc
    • everything under doc/
    • ngx_rewrite_options.cc in ngx_pagespeed
  • Also look over the open issues for mps and nps to find ones that are fixed but are still marked as open

Make edits to doc/release_notes.html, and send out a pull request for review.

Building binaries

We normally build the following files for release on dl.google.com:

  • mod_pagespeed: 32bit rpm
  • mod_pagespeed: 32bit deb
  • mod_pagespeed: 64bit rpm
  • mod_pagespeed: 64bit deb
  • mod_pagespeed: source tarball
  • psol: 32 bit headers+binary tarball
  • psol: 64 bit headers+binary tarball

We build these on GCE instances

Building mod_pagespeed rpms and debs

Note: if you're internal to google you already have the cloud sdk and a gcloud project; see the internal release supplement doc.

Install the cloud sdk for talking to GCE (https://cloud.google.com/sdk/) and create a gcloud project to do the builds under.

PATH=/path/to/cloud-sdk
CLOUDSDK_COMPUTE_ZONE=us-central1-a
BRANCH=34  # can't use a tag because CentOS git is too old to understand tags in "git clone -b BRANCH"
gcloud config set project [gcloud project name]
gcloud auth login
git checkout $BRANCH
install/build_on_vm.sh --build_branch=$BRANCH --centos
install/build_on_vm.sh --build_branch=$BRANCH --centos -- --32bit
install/build_on_vm.sh --build_branch=$BRANCH -- --skip_psol
install/build_on_vm.sh --build_branch=$BRANCH -- --32bit --skip_psol

build_on_vm.sh will spinup a vm, clone $RELEASE, build and test it and then (if successful) drop the final objects in ~/release/$RELEASE.

Building the source tarball

This is what the OpenSUSE maintainer builds from. Our build currently depends on OpenSSL 1.0.2 which our Ubuntu 14LTS lacks. You must build the tarball against a local build of OpenSSL 1.0.2:

cd /tmp
wget https://www.openssl.org/source/openssl-1.0.2j.tar.gz  # Or newer
tar -xzvf openssl-1.0.2j.tar.gz
cd openssl-1.0.2j
./config --prefix=/tmp/openssl shared && make && make install
cd RELEASE-CLIENT-DIRECTORY
SSL_CERT_DIR=/etc/ssl/certs PKG_CONFIG_PATH=/tmp/openssl/lib/pkgconfig LD_LIBRARY_PATH=/tmp/openssl/lib \ 
  devel/build_release_tarball.sh $RELEASE beta

Or, if you're on a system that does have OpenSSL >= 1.0.2, you can just run:

devel/build_release_tarball.sh $RELEASE beta

[need to opensource build_release_tarball.sh] [working here]

Clone this wiki locally