Steve-Dee-Designs
/
woocommerce
mirror of https://github.com/woocommerce/woocommerce.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document release process (https://github.com/woocommerce/woocommerce-blocks/pull/1614) 

* draft release process!

* ensure info in CONTRIBUTING is in release doc, remove section & add link

* fix link to release doc

* tweaks / typos / formatting after re-read

* tweak mia/follow up section title to more standard @todo

* add getting started docs for repo/dev tooling (required for releasing!)

* add intro sentence + link to required node versions + fix some grammar errors, heading level

* tweaks based on Timmy feedback:
- link to a real changelog commit
- add git pull to unambiguously illustrate "get on tip of branch"
- recommend multiple testers
+ sanity check => confidence check

* mention jetpack-autoloader

* reinstate "updating specific file on WPORG" section

* flesh out "release to wporg" so tools are more transparent +
+ add steps for testing/validating WPORG release

* clarify major / minor / patch process differences +
+ roughly define versions
+ mention Zenhub (tbc)

* clarification: cherry picking is patch releases only +
+ clarify readme update outcome

* tweaks & typos after reading start=>finish

* clarify versions info + tidy links in WPORG validate section

* tweaks & typos from Aljullu feedback

* flesh out pre-release testing steps:
- test oldest supported WP
- test existing blocks content / validation errors
- ALL of the testing steps are recommended :)
This commit is contained in:
Rua Haszard 2020-01-23 08:48:35 +13:00 committed by GitHub
parent d1737e76c2
commit e83819281c
2 changed files with 184 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
plugins/woocommerce-blocks/CONTRIBUTING.md
View File

@ -2,11 +2,28 @@
Thanks for your interest in contributing to WooCommerce Blocks! Below are some developer docs for working with the project.
To get started you need to install all required dependencies by running the following command in the plugin directory.
## Get started
```bash
npm install && composer install
```
### Required developer tools
- [`git`](https://git-scm.com)
- [`npm` and `node.js`](https://nodejs.org)
- [`composer`](https://getcomposer.org)
- A WordPress development environment - e.g. [`VVV`](https://varyingvagrantvagrants.org) or [`docker`](https://www.docker.com).
See [`package.json` `engines`](package.json) for details of required versions.
### Clone repo & install code dependencies
- Clone this repository locally - `git clone https://github.com/woocommerce/woocommerce-gutenberg-products-block.git`.
- Change directory to your repo folder, e.g. `cd woocommerce-gutenberg-products-block`.
- Install javascript and php dependencies - `npm install && composer install`.
### Run the plugin
- Ensure the repo folder is in the `wp-content/plugins` folder of your WordPress environment.
- Activate the `WooCommerce Blocks` plugin (should be dev version, e.g. `2.6.0-dev`).
- Edit a page or post in block editor - you should see WooCommerce blocks in the block inserter!
## NPM commands
@ -44,105 +61,9 @@ The test scripts use [wp-scripts](https://github.com/WordPress/gutenberg/tree/ma
Run `$ npm run package-plugin` to trigger install and build, and then create a zip file which you can use to install WooCommerce Blocks in WordPress admin.
## Releasing new versions of blocks
## Releases
These instructions cover new releases of the blocks plugin for those with commit access.
### Prerequisites
- Have [Github Hub](https://github.com/github/hub) cli installed and authenticated.
**Before any release** ensure you update:
- The `readme.txt` file supported versions, changelog and list of blocks if the release includes new blocks.
**Before a minor release** ensure you update:
- The release last major release branch you're basing this release from (e.g `release/2.5`), chances are you aren’t the last person who released and this branch will be outdated.
- `git checkout release/2.x` (e.g release/2.5).
- `git pull origin release/2.5`
### Creating release branches
When releasing a major or minor feature frozen version of Blocks (e.g. release candidate), create a new release branch from master named `release/X.X`. **This release branch is where you should create tags and releases from.**
If post-release fixes or changes are needed, create Pull Requests against **master**, but label the PR with the correct milestone. For example, if fixing an issue in Blocks 2.5, create a PR against master with a `2.5.x` milestone. Once approved and merged to master the same changes will be cherry picked to the release branch.
To do this:
- Switch to the release branch
- Run the command ([using HUB command line helper](https://hub.github.com/hub-am.1.html)): `hub am -3 http://URL-TO-PR`
- The command will tell you if the merge was successful. If not, you can cherry pick individual commits using [git cherry pick](https://git-scm.com/docs/git-cherry-pick) which is more time consuming.
- Push the changes to origin.
- After success, label the PR as `status: cherry-picked`. This lets everyone know the cherry picking has been completed.
You'll also need to manually update the changelog and version numbers in the release branch before tagging. There is a changelog helper script which can list changelog entries from merged PRs in a milestone:
`npm run changelog`
Follow the instructions, then add the changelog entries to the readme.txt file before committing to the release branch. Once all of this is done, you are safe to run the deploy scripts explained below.
If you're using the GitHub deploy script you no longer need to worry about version bumps; it's automated. The `$ npm run deploy` (explained below) will update version strings in `package.json`, `readme.text`, `src/Package.php`, and `woocommerce-gutenberg-products-block.php` for you, committing the changes to the current branch.
### Tagging new releases on GitHub
Tagging a new version on GitHub can be done by running the following script:
```shell
$ npm run deploy
```
This will trigger a build and then run the release script (found in `/bin/github-deploy.sh`). This tags a new version and creates the GitHub release from your current branch.
**Important:** Before running the deploy script ensure you have committed all changes to GitHub and that you have the correct branch checked out that you wish to release.
If you want to add additional details or a binary file to the release after deployment, [you can edit the release here](https://github.com/woocommerce/woocommerce-gutenberg-products-block/releases).
### Bumping the version in MASTER after releasing a tag
After you release a new version from a release branch there are some other steps to do to keep `master` up to date.
- If you released an update with a changelog, create a commit/PR to master with the new changelog entries.
- Create a commit to master that updates the version to the next minor with a `-dev` suffix. For example, if you just released `2.5.0`, you'd do an update changing the version to `2.6.0-dev`. See an [example here](https://github.com/woocommerce/woocommerce-gutenberg-products-block/commit/e27f053e7be0bf7c1d376f5bdb9d9999190ce158).
### Pushing new releases to WordPress.org
If you have SVN commit access to the WordPress.org plugin repository you can run the following script to prepare a new version:
```shell
$ npm run release
```
This will ask for a tagged version number, check it out from GitHub, check out the SVN repository, and prepare all files. It will give you a command when it's finished to do the actual commit; you have a chance to test/check the files before pushing to WordPress.org.
**Important:** Before running the release script ensure you have already pushed a new release to GitHub.
## Updating a single file in WordPress.org
Sometimes, we need to update a single file in WordPress.org without wanting to do a full release, for example, updating the `readme.txt` versions or descriptions. In order to do that, refer to the _[Editing Existing Files](https://developer.wordpress.org/plugins/wordpress-org/how-to-use-subversion/#editing-existing-files)_ section of the Subversion guide in developer.wordpress.org or follow these steps:
1. Checkout the plugin repo:
```
svn co "http://plugins.svn.wordpress.org/woo-gutenberg-products-block/"
cd woo-gutenberg-products-block
```
2. Modify the files you want to change in `trunk` or `tags/x.y.z`.
3. Check your changes with:
```
svn stat
svn diff
```
4. Commit the changes to the server:
```
svn ci -m "Updated readme.txt description"
```
See [RELEASE.md](RELEASE.md).
## Publishing `@woocommerce/block-library`

161
plugins/woocommerce-blocks/RELEASE.md Normal file
View File

@ -0,0 +1,161 @@
# Releases
This document outlines the process of releasing new versions of the blocks plugin.
## Prerequisites - what you need to release WooCommerce Blocks
- You should be set up for development - for more info see [`CONTRIBUTING.md`](CONTRIBUTING.md).
- Install & set up [GitHub hub](https://hub.github.com) tools.
- Configure a GitHub token for release scripts to use.
- https://github.com/settings/tokens
- Select the following permissions:
- `admin:org`
- `public_repo`
- `read:user`
- Ensure your token is available to scripts, e.g. `export GH_API_TOKEN={YOUR-TOKEN}` or similar.
- Get WPORG plugin svn commit access - ask a team member.
_Outcome_: __You are equipped to ship a release!__
## Release process
### Lead-up to release
#### Ensure release development is complete
- For _major_ and _minor_ releases, we use ZenHub.
- For _patch_ releases, we use GitHub milestones - [example](https://github.com/woocommerce/woocommerce-gutenberg-products-block/milestone/41).
- Ensure all issues/PRs intended for this release are merged, closed and linked to release.
- All PRs should have changelog entry, or `skip-changelog` tag.
- Check with the team to confirm any outstanding or in progress work.
Note: changelog should be formatted like this in PR description. Note the preceding `> ` - this is required by changelog script.
```md
### Changelog
> bug: Fix bug in Safari and other Webkit browsers that was causing the All Products block to show 0 results when resetting the sort value.
```
_Outcome_: __Team is aware of release and in agreement about what fixes & features are included.__
#### Ensure release branch includes all relevant fixes
- Make release branch (if needed).
- For _major_ and _minor_ releases, create branch: `release/X.X`.
- For _patch_ releases, the branch should already exist.
- Ensure your local checkout is updated to the tip of the release branch.
- For _patch_ releases, cherry pick relevant PRs into the release branch:
- If PR is already labelled `status: cherry-picked 🍒` then continue to next PR.
- Ideally, use GitHub Hub to cherry pick the PR - `hub am -3 {http://URL-TO-PR}`.
- If there are serious conflicts or extensive differences between `master` and release branch, you may need to take more care:
- Manually cherry pick individual commits using git - `git cherry-pick {COMMIT-HASH}`.
- Or in some cases, manually craft a new PR with appropriate changes, targeting release branch.
- Push the release branch to origin (so changes are in GitHub repo).
- Label the PR: `status: cherry-picked 🍒`.
_Outcome_: __Release branch has all relevant changes merged & pushed.__
### Prepare release
#### Ensure release branch readme is up to date
- Run changelog script `npm run changelog` to get changelog txt for readme. Changelog content will be output to screen by script.
- Add changelog section for release, e.g. [`= 2.5.11 - 2020-01-20 =`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/commit/74a41881bfa456a2167a52aaeb4871352255e328).
- Copy-paste the changelog content into `readme.txt`.
- Make any other changes to readme as needed - e.g. support versions changing, new blocks.
- Push readme changes to release branch on origin repo.
- Note: you can push your readme changes directly to branch – no need for a PR & review process.
_Outcome_: __Release branch has `readme.txt` is updated with release details.__
#### Build zip & smoke test
- Ensure you are on the tip of the release branch, e.g. `git pull origin release/2.5`
- Update dependencies – `npm ci`.
- Run a production build - `npm run build`.
- Run package script to get a zip to test `npm run package-plugin`.
- Smoke test built release zip:
- At least one other person should test the built zip - ask a teammate to help out.
- Test in a clean environment, e.g. Jurassic.Ninja site.
- Test existing WooCommerce Blocks content works correctly after update (no block validation errors).
- Test to confirm blocks are available and work correctly in oldest supported WordPress version (e.g. 5.0).
- Confidence check - check blocks are available and function.
- Test to confirm new features/fixes are working correctly.
- Smoke test – test a cross section of core functionality.
_Outcome_: __Confident that source code is ready for release: intended fixes are working correctly, no release blockers or build issues.__
### Release!
#### Tag release on GitHub
- Prepare tagged release on github `npm run deploy`.
- Note: the script automatically updates version numbers (commits on your behalf).
- Edit release, add changelog info to Github release notes.
- Check release repo tag is correct - checkout, smoke test/confidence check.
_Outcomes_: __Version numbers updated in source code & developers can test tagged release.__
#### Release to WPORG
- Run `npm run release`. This script clones a copy of the source code to your home folder, and outputs an `svn` command to push release up to WPORG.
- Push release to WPORG using `svn`.
- Run generated svn command to commit to WPORG svn repo.
- The command should look like this: `cd /Users/{YOU}/blocks-deployment/woo-gutenberg-products-block-svn && svn ci -m "Release 2.5.11, see readme.txt for changelog."`
- Commit should complete successfully with a message like `Committed revision 2231217.`.
- Confirm that the WPORG release is updated and correct:
- Changelog, `Version` & `Last updated` on [WPORG plugin page](https://wordpress.org/plugins/woo-gutenberg-products-block/).
- Confirm svn tag is correct, e.g. [2.5.11](https://plugins.svn.wordpress.org/woo-gutenberg-products-block/tags/2.5.11/).
- Confirm [WooCommerce.com plugin page](https://woocommerce.com/products/woocommerce-gutenberg-products-block/) is updated.
- Download zip and smoke test.
- Test updating plugin from previous version.
_Outcome_: __Customers can install/update via WPORG; WPORG plugin page is up to date__.
### After release
#### Update `master` with release changes
- Ensure changelog is up to date on master.
- For _major_ & _minor_ releases, update version on master with dev suffix, e.g. [`2.6-dev`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/commit/e27f053e7be0bf7c1d376f5bdb9d9999190ce158).
#### Clean up release milestone / Zenhub
- For _patch_ releases, close the milestone in GitHub.
- For _major_ & _minor_ releases - tbc
## Appendix: Versions
We have _major_, _minor_ and _patch_ releases.
For example:
- version == 2.5.11
- 2 == _major_ version; has breaking changes or major new features
- 5 == _minor_ version; has new features
- 11 == _patch_, aka point / revision / fix; has bug fixes and improvements to existing features
- 2.0 is a _major_ release
- 2.5 is a _minor_ release
- 2.5.11 is a _patch_ release
There are some differences to our release process for each kind of release - these are detailed in the steps above.
## Appendix: updating a specific file on WPORG
Sometimes, we need to update a single file in WordPress.org without wanting to do a full release, for example, updating the `readme.txt` versions or descriptions. In order to do that, refer to the _[Editing Existing Files](https://developer.wordpress.org/plugins/wordpress-org/how-to-use-subversion/#editing-existing-files)_ section of the Subversion guide in developer.wordpress.org or follow these steps:
1. Checkout the plugin repo:
```
svn co "http://plugins.svn.wordpress.org/woo-gutenberg-products-block/"
cd woo-gutenberg-products-block
```
2. Modify the files you want to change in `trunk` or `tags/x.y.z`.
3. Check your changes with:
```
svn stat
svn diff
```
4. Commit the changes to the server:
```
svn ci -m "Updated readme.txt description"
## `@todo` Missing info to link to / document
- Release milestones
- Relationship to Woo core release
- Testing blocks plugin as included in Woo core (do we do this?)
- Policy for inclusion in major / minor / fix releases - i.e. how we use versioning
- ["Legacy"](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/add/release-process/assets/js/legacy/README.md) stuff - is this relevant to releases?
- `jetpack-autoloader` versions in this plugin vs. wc-admin vs. WooCommerce core
```