# Releasing Storefront

This document outlines the process for releasing new versions of the Storefront theme.

Note that Storefront bumps the minor version (2.x.0) between releases and the next version after 2.9.0 would be 3.0.0, [similar to WordPress core version numbering](https://make.wordpress.org/core/handbook/about/release-cycle/version-numbering/). Patch versions are used for fix releases that are deployed outside the usual release schedule (this is rare).

## Steps

The release process has three main phases:

- Building and testing a release candidate (RC) - steps 1-3 below.
- Fixing any issues that arise during RC testing.
- Building and releasing the final release - steps 1 & 4-6.

Depending on the release, releasing and testing an RC may not be necessary (i.e. skip step 2); for larger releases, multiple RCs may be worthwhile (i.e. repeat steps 1-3).

### 1 – Prepare code & build zip file

- Confirm all work intended for release (fixes, features) is completed and merged to release branch.
  - Typically we release Storefront from default branch (`trunk`).
    - A release branch (e.g. `release/2.7`) is used as needed, e.g. patch releases (rare).
  - Ensure testing instructions for all enhancements are [available on the wiki](https://github.com/woocommerce/storefront/wiki/Release-Testing-Instructions).
- Review any [dependency updates since the last release](https://github.com/woocommerce/storefront/pulls?q=is%3Apr+author%3Aapp%2Frenovate+is%3Aclosed).
  - Is extra testing needed?
  - Add release notes as appropriate (e.g. major versions or risky/impactful updates).
- Ensure your local checkout is on release branch and up to date!
- Update version numbers and release date (if you're building an RC version make sure you use the correct version strategy - eg. 2.6.1-rc1):
  - `readme.txt`
  - `style.scss`
  - `package.json` and `package-lock.json`
- Confirm/update metadata in `readme.txt`, e.g. “tested up to” version.
- Finalise changelog and add to `readme.txt`.
- Clean install of dependencies: `npm ci`.
- Run a production build: `npm run build`.
- Ensure all changes above are committed and pushed (you should not have uncommitted changes):
  - Version numbers, dates, metadata
  - Changelog
  - Translation (`.pot`) file. Note this file is generated by production build.

__*Outcome*: You know what changes are in the release, what might be impacted, and what testing is required.__

__*Outcome*: A `storefront.zip` file that you can test with.__

__*Outcome*: All release changes including versions and POT file are committed and pushed to release branch.__

### 2 – Publish RC build (optional)

- Publish release on [GitHub](https://github.com/woocommerce/storefront/releases).
  - Upload release zip.
  - Use this format for tag: `version/1.2.3-rc.1`.
  - Paste changelog into “release details” field.
  - Check `This is a pre-release` tickbox.

__*Outcome*: A `storefront.zip` file is available to the community and other stakeholders for testing and feedback.__

### 3 – Test & QA

Note: all new code should have been fully tested during development. This test pass is to confirm that there are no major regressions or bugs, aka [“happy path”](https://en.wikipedia.org/wiki/Happy_path) or [smoke testing](http://softwaretestingfundamentals.com/smoke-testing/).

Testing documentation is available in the [wiki](https://github.com/woocommerce/storefront/wiki/):

- [Checklist of main flows and features](https://github.com/woocommerce/storefront/wiki/Testing-Storefront:-flows-and-features).
- [Testing instructions for each release (2.5.7 and newer)](https://github.com/woocommerce/storefront/wiki/Release-Testing-Instructions).

- __Recommended__: Test in a clean environment, similar to a typical hosting environment. Avoid testing in your development environment.
- __Recommended__: Test with a snapshot of data from a real store, with customers, products and reviews.

Perform testing as appropriate for the release. Use your judgement to ensure effective efficient testing – e.g. for small releases, 1 tester (you) x ~1 hour. For larger releases, allow more time and request assistance from team, testing guild as necessary.

At a minimum, test the following:

- Spot-check a cross-section of key flows - e.g. timeboxed exploratory testing.
- Confirm recent fixes and features (this release, previous release) are working correctly and haven’t regressed.

__If there are blocking issues or major regressions, the process stops here!__ (So they can be fixed.)

__*Outcome*: You (release lead) are confident that the product is ready for release, and a safe & worthwhile upgrade for merchants.__

### 4 – Launch release

Now we get to release!

- If necessary, build final `storefront.zip` with correct (non-RC) version number (repeat step 1).
- Publish release on [GitHub](https://github.com/woocommerce/storefront/releases).
  - Upload release zip.
  - Use this format for tag: `version/1.2.3`.
  - Paste changelog into “release details” field.
- Upload to [WordPress.org](https://wordpress.org/themes/upload/). (You'll need access to the `Automattic` user account.)
- Publish any documentation updates.
- Post an announcement on the [dev blog](https://woocommerce.wordpress.com/category/storefront/).

__*Outcome*: Merchants are using the new Storefront, your new features are live, stores are working better, customers are happier!__

### 5 – Post-release checks

- Confirm WordPress.org version is correct, sites can auto-update.
- Update [demo site](https://themes.woocommerce.com/storefront/):
  - Clone/update [demo.woothemes.com](https://github.com/automattic/demo.woothemes.com) repository master branch.
  - Update storefront – i.e. unzip and replace `themes/storefront`.
  - Commit & push.
  - Site should automatically build & deploy.
- Confirm demo site is running correct version and nothing is broken.