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

Update documentation indexes and add checkout docs (https://github.com/woocommerce/woocommerce-blocks/pull/2720) 

* Fix existing indexes

* Update indexes

* Stock docs
This commit is contained in:
Mike Jolley 2020-06-16 16:50:09 +01:00 committed by GitHub
parent e26b60f00e
commit 340cf01255
8 changed files with 338 additions and 229 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
plugins/woocommerce-blocks/docs/blocks/README.md Normal file
View File

@ -0,0 +1,7 @@
# WooCommerce Blocks Handbook
This folder contains documentation for specific Blocks and Blocks functionality.
| Document | Description |
| --------------------------------------------------------- | ------------------------------------------------------ |
| [Stock Reservation during Checkout](stock-reservation.md) | This doc covers the Checkout Stock Reservation system. | |

BIN
plugins/woocommerce-blocks/docs/blocks/checkout.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 112 KiB

BIN
plugins/woocommerce-blocks/docs/blocks/reserve-stock.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

95
plugins/woocommerce-blocks/docs/blocks/stock-reservation.md Normal file
View File

@ -0,0 +1,95 @@
# Stock Reservation during Checkout
To prevent multiple customers trying to purchase the same stock when limits are in place, both WooCommerce ([4.3+](https://github.com/woocommerce/woocommerce/pull/26395#pullrequestreview-430633490)) and the Blocks plugin have a stock reservation system which is used during checkout.
## The Reserved Stock Database Table
The table which tracks reserved stock is named `wc_reserved_stock`, and the schema contains the following columns:
| Key | Type | Description |
| ---------------- | ------------ | ----------------------------------- |
| `order_id` | `bigint(20)` | ID of the order. |
| `product_id` | `bigint(20)` | ID of the product or variation. |
| `stock_quantity` | `double` | The amount of stock reserved. |
| `timestamp` | `datetime` | The timestamp the hold was created. |
| `expires` | `datetime` | The timestamp the hold expires. |
The primary key is a combination of order and product ID to prevent multiple holds being created for the same order if checkout is performed multiple times.
### Usage Example
This example shows how stock would be reserved programmatically for an order using the `ReserveStock` class which acts as an interface between the checkout and the `wc_reserved_stock` table.
```php
$reserve_stock = new ReserveStock();
try {
// Try to reserve stock for 10 mins, if available.
$reserve_stock->reserve_stock_for_order( $order_object, 10 );
} catch ( ReserveStockException $e ) {
// ...handle error
}
```
This either holds stock, or rejects the order if the stock cannot be reserved for whatever reason. Stock is immediately released when defined time passes, or when the order changes to a “paid” status such as processing, on-hold, or complete.
Some things worth noting:
- Before stock can be reserved, an order must exist.
- Stock is reserved for a defined period of time before it expires; these expired rows are cleaned up periodically and do not affect queries for stock levels.
- If an order is changed, stock should be reserved again. The `ReserveStock` class will renew any existing holds and remove any invalid ones for the current order.
### What about concurrency?
To mitigate concurrency issues (where multiple users could attempt to reserve the same stock at the same time, which is a risk on busier stores) the query used to check and reserve stock is performed in a single, atomic operation.
This operation locks the tables so that separate processes do not fight over the same stock. If there were two simultaneous requests for the same stock at the same time, one would succeed, and one would fail.
## The Reserve Stock Process
![Reserve Stock Process](reserve-stock.jpg)
### How the queries work
On the technical side:
- The `ReserveStock` class joins the `wc_reserved_stock` table to `wp_posts` using the post/order ID
- Only non-expired rows are used
- Only draft/pending order rows are used
Here is an example query getting stock for Product ID 99 and excluding order ID 100.
```sql
SELECT COALESCE( SUM( stock_table.`stock_quantity` ), 0 )
FROM wp_wc_reserved_stock stock_table
LEFT JOIN wp_posts posts ON stock_table.`order_id` = posts.ID
WHERE posts.post_status IN ( 'wc-checkout-draft', 'wc-pending' )
AND stock_table.`expires` > NOW()
AND stock_table.`product_id` = 99
AND stock_table.`order_id` != 100
```
When creating holds on product stock, this query is used again, but it also creates locks to prevent stock being assigned to multiple orders if they come in around the same time:
```sql
INSERT INTO wp_wc_reserved_stock ( `order_id`, `product_id`, `stock_quantity`, `timestamp`, `expires` )
SELECT 99, 100, 1, NOW(), ( NOW() + INTERVAL 10 MINUTE ) FROM DUAL
WHERE ( $query_for_stock FOR UPDATE ) - ( $query_for_reserved_stock FOR UPDATE ) >= 1
ON DUPLICATE KEY UPDATE `expires` = VALUES( `expires` )
```
In the above code snippet:
- `$query_for_stock` is a subquery getting stock level from the post meta table, and `$query_for_reserved_stock` is the query shown prior.
- The `FOR UPDATE` part locks the selected rows which prevents other requests from changing those values until we’ve inserted the new rows.
- The `ON DUPLICATE KEY` part updates an existing row if one already exists for that order/item.
## How this all fits into Checkout Block vs Traditional Checkout
The point of which stock is reserved differs between the new Block based checkout and the traditional checkout, the main difference being that the Block based checkout reserves stock on entry so the customer isn't forced to fill out the entire checkout form unnecessarily.
![Checkout Processes](checkout.jpg)
You can see that in both Checkouts, if stock cannot be reserved for all items in the order, either the order is rejected, or the user cannot proceed with checkout.

12
plugins/woocommerce-blocks/docs/contributors/README.md Normal file
View File

@ -0,0 +1,12 @@
# Contributing
This folder contains documentation for developers and contributors looking to get started with WooCommerce Block Development.
| Document | Description |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [Getting Started](getting-started.md) | This doc covers tooling and creating builds during development. |
| [Coding Guidelines](coding-guidelines.md) | This doc covers development best practices. |
| [Smoke Testing](smoke-testing.md) | This doc explains how to smoke test key Blocks functionality. |
| [JavaScript Testing](javascript-testing.md) | This doc explains how to run automated JavaScript tests. |
| [Component Testing & Development (with Storybook)](storybook.md) | This doc explains how to use Storybook to test and develop components in isolation. |
| [Block Script Assets](block-assets.md) | This doc explains how Block Script Assets are loaded and used. |

31
plugins/woocommerce-blocks/docs/readme.md
View File

@ -2,25 +2,12 @@
The WooCommerce Blocks Handbook provides documentation for designers and developers on how to extend or contribute to blocks, and how internal developers should handle new releases.
## Table of Contents
**Contributing**
- [Getting Started](contributors/getting-started.md)
- [Coding Guidelines](contributors/coding-guidelines.md)
- [Smoke Testing](contributors/smoke-testing.md)
- [JavaScript Testing](contributors/javascript-testing.md)
- [Component Testing & Development (with Storybook)](contributors/storybook.md)
**Releases**
- [Releasing New Versions](releases/readme.md)
- [WordPress Update Testing Checklist](releases/wordpress-update-testing-checklist.md)
**API documentation**
- [Store API documentation](../src/RestApi/StoreApi/README.md)
**For themes**
- [Theming documention](theming/README.md)
| Document | Description |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Contributing](contributors/getting-started.md) | These documents explain how you can contribute to the development of the blocks plugin, development best practices, and how to help with testing. |
| [Releases](releases/readme.md) | These documents cover how to release and test new versions of the blocks plugin. |
| [Blocks](blocks/README.md) | This documentation covers functionality specific to certain Blocks. |
| [Block Client APIs](block-client-apis/README.md) | This documentation covers API interfaces within Blocks. In most cases, these docs describe APIs and interfaces that are internal only, and thus are provided to assist with developing the blocks in this repository. Documentation will tend to focus on high level overviews. |
| [Store API (REST API)](../src/StoreApi/README.md) | These documents cover the Store API used to get product data on the frontend. |
| [Extensibility](extensibility/README.md) | These documents cover extensibility of WooCommerce Blocks. |
| [Theming](theming/README.md) | These documents cover theming for blocks, styles, CSS classnames and other theming best practices. |

210
plugins/woocommerce-blocks/docs/releases/handling-releases.md Normal file
View File

@ -0,0 +1,210 @@
# Handling 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 [this doc](../contributors/getting-started.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
- Github milestones are used for all releases. We do releases every two weeks from the latest release milestone - [example](https://github.com/woocommerce/woocommerce-gutenberg-products-block/milestone/43)
- If a patch release is needed, then the milestone for the patch release is created and a decision will be made whether it just includes `cherry-picked` changes, or all the changes currently slated from the current release milestone. If the latter, then all the issues and pulls in the current release milestone are moved to the patch release, and the the release is built from the patch release branch rebased on `main`. In **most cases**, patch releases will involve cherry-picking.
- 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.
#### Create a release pull request
Using the [release pull request template](../../.github/release_pull_request_template.md), create a pull request for the release branch you just created. This pull request will have changes merged to the min branch, but might not be a straight merge if it contains cherry-picked commits. The pull request also contains the checklist to go over as a part of the release along with being a place to contain all planning/communication around the release. The checklist should be completed and the pull request has an approved review from at least one team member before you do the Github deploy or release the plugin to WordPress.org.
### Patch releases against latest main branch
If it's determined a patch release will include the latest main branch:
- Ensure your local checkout is updated to the tip of the release branch.
- Rebase the release branch for the patch release against `main`.
- Move all closed issues and pulls from the current release milestone into the patch release milestone.
- Push the release branch to origin (so changes are in GitHub repo).
### Patch releases with cherry-picking.
This is for releases where just fixes specific to the branch are released and not the latest changes in `main`.
- Ensure your local checkout is updated to the tip of the release branch.
- 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 cherry-pick {PR-COMMIT-URL}`.
- If there are serious conflicts or extensive differences between `main` 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 🍒`.
### Minor/Major releases
- Ensure your local checkout is updated to the tip of the release branch.
_Outcome_: **Release branch has all relevant changes merged & pushed and there is a corresponding release pull request created for the release.**
### 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.
- The above script will automatically generate changelog entries from a milestone (you will be asked about the milestone name in the 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.
- Create testing notes for the release (you might be able to copy some from the pulls included in the release). Add the notes to [`docs/testing/releases`](../testing/releases/) (and update the [README.md index](../testing/releases/README.md) there)
_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.
- Tests performed should be recorded and listed in the release pull request.
- Ask a team member to review the changes in the release pull request and for anyone who has done testing that they approve the pull request.
_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 `main` branch with release changes
- Merge the release branch back into `main` (without the branch being up to date with `main`). This may have merge conflicts needing resolved if there are cherry-picked commits in the release branch.
- Do not delete the branch (release branches are kept open for potential patch releases for that version)
- For _major_ & _minor_ releases, update version on `main` with dev suffix, e.g. [`2.6-dev`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/commit/e27f053e7be0bf7c1d376f5bdb9d9999190ce158).
#### Clean up release milestone / Zenhub
- Edit the milestone and add the current date as the due date (this basically is used for easy reference of when the milestone was completed).
- Close the milestone.
- If you didn't release a patch release, create a milestone for the next minor release.
- Close any epics that are completed as of this release and remove any unfinished issues in that from the epic.
#### Create pull request for updating the package in WooCommerce core.
If the tagged release should be updated in WooCommerce core, do this immediately following our release.
- Create the pull request in the [WooCommerce Core Repository](https://github.com/woocommerce/woocommerce/) that [bumps the package version](https://github.com/woocommerce/woocommerce/blob/master/composer.json) for the blocks package to the version being pulled in.
- Copy the release pull request notes for that tag (and merge any notes from previous tags if you're bumping up from non consecutive versions) into the pull request description.
- Run through the testing checklist to ensure everything works in that branch for that package bump. **Note:** Testing should include ensuring any features/new blocks that are supposed to be behind feature gating for the core merge of this package update are working as expected.
- Verify and make any additional edits to the pull request description for things like: Changelog to be included with WooCommerce core, additional communication that might be needed elsewhere, additional marketing communication notes that may be needed etc.
- After the checklist is complete and the testing is done, it will be up to the WooCommerce core team to approve and merge the pull request.
_Outcome:_ The package is updated in WooCommerce core frequently and successfully merged to WooCommerce main branch as a stable release.
## 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"
```

212
plugins/woocommerce-blocks/docs/releases/readme.md
View File

@ -1,210 +1,8 @@
# Releases
This document outlines the process of releasing new versions of the blocks plugin.
This folder contains documentation on how to release and test 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 [this doc](../contributors/getting-started.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
- Github milestones are used for all releases. We do releases every two weeks from the latest release milestone - [example](https://github.com/woocommerce/woocommerce-gutenberg-products-block/milestone/43)
- If a patch release is needed, then the milestone for the patch release is created and a decision will be made whether it just includes `cherry-picked` changes, or all the changes currently slated from the current release milestone. If the latter, then all the issues and pulls in the current release milestone are moved to the patch release, and the the release is built from the patch release branch rebased on `main`. In **most cases**, patch releases will involve cherry-picking.
- 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.
#### Create a release pull request
Using the [release pull request template](../../.github/release_pull_request_template.md), create a pull request for the release branch you just created. This pull request will have changes merged to the min branch, but might not be a straight merge if it contains cherry-picked commits. The pull request also contains the checklist to go over as a part of the release along with being a place to contain all planning/communication around the release. The checklist should be completed and the pull request has an approved review from at least one team member before you do the Github deploy or release the plugin to WordPress.org.
### Patch releases against latest main branch
If it's determined a patch release will include the latest main branch:
- Ensure your local checkout is updated to the tip of the release branch.
- Rebase the release branch for the patch release against `main`.
- Move all closed issues and pulls from the current release milestone into the patch release milestone.
- Push the release branch to origin (so changes are in GitHub repo).
### Patch releases with cherry-picking.
This is for releases where just fixes specific to the branch are released and not the latest changes in `main`.
- Ensure your local checkout is updated to the tip of the release branch.
- 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 cherry-pick {PR-COMMIT-URL}`.
- If there are serious conflicts or extensive differences between `main` 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 🍒`.
### Minor/Major releases
- Ensure your local checkout is updated to the tip of the release branch.
_Outcome_: **Release branch has all relevant changes merged & pushed and there is a corresponding release pull request created for the release.**
### 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.
- The above script will automatically generate changelog entries from a milestone (you will be asked about the milestone name in the 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.
- Create testing notes for the release (you might be able to copy some from the pulls included in the release). Add the notes to [`docs/testing/releases`](../testing/releases/) (and update the [README.md index](../testing/releases/README.md) there)
_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.
- Tests performed should be recorded and listed in the release pull request.
- Ask a team member to review the changes in the release pull request and for anyone who has done testing that they approve the pull request.
_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 `main` branch with release changes
- Merge the release branch back into `main` (without the branch being up to date with `main`). This may have merge conflicts needing resolved if there are cherry-picked commits in the release branch.
- Do not delete the branch (release branches are kept open for potential patch releases for that version)
- For _major_ & _minor_ releases, update version on `main` with dev suffix, e.g. [`2.6-dev`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/commit/e27f053e7be0bf7c1d376f5bdb9d9999190ce158).
#### Clean up release milestone / Zenhub
- Edit the milestone and add the current date as the due date (this basically is used for easy reference of when the milestone was completed).
- Close the milestone.
- If you didn't release a patch release, create a milestone for the next minor release.
- Close any epics that are completed as of this release and remove any unfinished issues in that from the epic.
#### Create pull request for updating the package in WooCommerce core.
If the tagged release should be updated in WooCommerce core, do this immediately following our release.
- Create the pull request in the [WooCommerce Core Repository](https://github.com/woocommerce/woocommerce/) that [bumps the package version](https://github.com/woocommerce/woocommerce/blob/master/composer.json) for the blocks package to the version being pulled in.
- Copy the release pull request notes for that tag (and merge any notes from previous tags if you're bumping up from non consecutive versions) into the pull request description.
- Run through the testing checklist to ensure everything works in that branch for that package bump. **Note:** Testing should include ensuring any features/new blocks that are supposed to be behind feature gating for the core merge of this package update are working as expected.
- Verify and make any additional edits to the pull request description for things like: Changelog to be included with WooCommerce core, additional communication that might be needed elsewhere, additional marketing communication notes that may be needed etc.
- After the checklist is complete and the testing is done, it will be up to the WooCommerce core team to approve and merge the pull request.
_Outcome:_ The package is updated in WooCommerce core frequently and successfully merged to WooCommerce main branch as a stable release.
## 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"
```
| Document | Description |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [Handling Releases](handling-releases.md) | How to build, deploy, and release new versions of the Blocks plugin. |
| [WordPress Update Testing Checklist](wordpress-update-testing-checklist.md) | A checklist of things to test before a new release. |