Skip to content

Plugin Deployment

Jump to bottom
Fulvio Notarstefano edited this page Dec 14, 2023 · 10 revisions

Deployment

This guide is about deploying plugins that utilize Sake for deployment to the WooCommerce.com marketplace, the WordPress plugins directory, or simply hosted on GitHub.

Versioning

Sake assumes plugins will follow semantic versioning (SemVer).

When deploying, you'll determine what the version should be (patch, minor, or major) based on the changelog.

The concepts described in the Semantic Versioning specification will be applied as closely as is possible to versioning plugins. The specification refers largely to a software's "public API", which doesn't necessarily apply to every plugin, but we can consider the admin/frontend interface to be a form of "public API" as well. Some highlights:

  1. Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.
  2. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.
  3. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.
  4. A pre-release version MAY be denoted by appending a dash and a series of dot separated identifiers immediately following the patch version. Identifiers MUST be comprised of only ASCII alphanumerics and dash [0-9A-Za-z-]. Pre-release versions satisfy but have a lower precedence than the associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

Point number 4 can be used to assign a plugin a provisional version number when performing ongoing development which will be part of a future commit of unknown size/version increment. This provisional version number shall be updated to a final version number prior to release.

An initial internal release candidate may be revisioned as a 0-leading number, ie 0.1 up until it is released, at which point all reference to the pre-release version shall be replaced with 1.0, except in the case where a pre-release plugin was written for and released to a client.

Any pre-release version numbers should be replaced with the final version number when deploying. This includes the changelog.txt entry, main plugin file header and optional version constant, as well as any @since or other comment references or version comparison checks, or any other place in code.

Deploying

Typically, all plugin deploys are done via Sake, but some may be done manually. The following section contains a description of the plugin release process, first with a pre-flight checklist:

  • Ensure the changelog is completed with a list of changes and additions
  • Ensure that the plugin has a development version in the changelog and main plugin file header / version constant
  • Merge the plugin PR into master and delete the PR branch
  • Ensure you're on master and pull changes in wc-plugins and ensure your local copy is clean without any uncommitted changes
  • For automated deploys:
  • For manual deploys:

Automated Deploy

Setting up your environment

Add these entries to your .bash_profile (or .zprofile if you're on zsh):

export GITHUB_USERNAME="yourusername"
export GITHUB_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export WC_CONSUMER_KEY="ck_xxxxxxx"
export WC_CONSUMER_SECRET="cs_xxxxxxxxx"
export WP_SVN_USER="SkyVerge" 
export SAKE_PRE_RELEASE_PATH="~/path/to/pre-releases/folder/"
export SAKE_PRODUCTION_GITHUB_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export DEPLOY_DOCS="skyverge/wc-plugins-sales-docs"

Where

  • GITHUB_USERNAME is the username associated with your GitHub account
  • GITHUB_API_KEY is your personal access token with 'gist', 'repo', and 'user' scopes. These can be generated on the Applications settings page.
  • WC_CONSUMER_KEY & WC_CONSUMER_SECRET listed under the "WooCommerce API" entry in 1Password
  • WP_SVN_USER is the username used to commit plugin changes to the WordPress.org SVN repository.
  • SAKE_PRE_RELEASE_PATH is the path to the SkyVerge pre-releases folder. e.g. ~/Dropbox (SkyVerge)/skyverge-prereleases or ${DROPBOX_PATH}/skyverge-prereleases/ if you had previously set DROPBOX_PATH
  • SAKE_PRODUCTION_GITHUB_API_KEY is a personal access token with gist, repo, and user scopes for the WooCommerce mirror repositories. These can be generated on the Applications settings page.
  • DEPLOY_DOCS is the owner and name of the repository where Saké should create documentation issues. The default value above should work for all of our plugins.

Deploy via Sake

Run composer install --no-dev as a sanity check to confirm your vendor directory is clean. This can help to prevent errors during npx sake deploy caused by uncommitted changes in the vendors directories (exussum12/coverage-checker has uncommitted changes appears sometimes after using composer phpcs-diff).

Open your favorite command line app and try:

cd /path/to/wc-plugins/<plugin-dir>

composer install --no-dev

Then, once you have set everything up as instructed above:

cd /path/to/wc-plugins/<plugin-dir>

npx sake deploy

Note: if you are deploying a compatibility release for a WC version that was not released yet (RC) or a release on top of such compatibility release, you can add the tested_up_to_wc_version parameter to update the WC tested up to header. For instance:

npx sake deploy --tested_up_to_wc_version=3.8.0

You will be prompted to select the plugin version that is to be deployed. The prompt will show you the latest changes and the current version. Use your arrow keys to select the best suited version and hit return to let Sake continue.

Deploy to WooCommerce

Once the release has gone through the main deploy process, you will be prompted to confirm you want to upload the final release zip to woocommerce.com:

Upload plugin to WooCommerce.com?

At this point, you should visit the plugin's mirror repo at github.com/woocommerce/{plugin-slug} and view the single deploy commit, usually named something like Update {Plugin Name} to x.x.x. Check the changes in that commit to confirm that there are no surprises, like files added or deleted that shouldn't have been. Once confirmed, you can confirm the prompt.

The plugin will be uploaded to WooCommerce.com! After that, it'll take around 5 minutes to become publicly available.

What to do if the commit includes unexpected changes?

If the commit includes unexpected changes, you should decline the prompt to prevent the new version of the plugin from being uploaded to WooCommerce.com.

In that case, the new version doesn't go out, so we can remove the unexpected changes without bumping the patch version. We can delete the releases and tags from the repos and re-deploy:

  1. Delete the release and tag from the mirror repo
  2. Delete the release and tag from the wc-plugins repo
  3. Revert the versioning commit on the mirror repo
  4. Revert the versioning commit on the wc-plugins repo

After that, confirming you don't have any local changes, you can re-run the sake command.

Watch for confirmation

For each plugin you deploy, you'll see a notification in #woocommerce Slack for the successful release. You should make sure and confirm that each deployed plugin gets a successful notification, and re-upload any plugins that fail.

Common Failures

  • During deploy
    • Error: WC API: Sorry, you don't have permission to access this resource. (wccom_rest_cannot_manage_product) - This usually indicates that you don't have the WC_CONSUMER_KEY and WC_CONSUMER_SECRET values defined in your environment.
  • After deploy
    • virus! - This usually means that their zip scanning failed for some reason, and that the plugin needs to be re-uploaded

Product Pages

Sometimes the product pages take extra time to update due to caching. If a new version is taking a long time to show up, you can check the list of versions in the marketplace admin to confirm all is well. If the new version is there, it'll eventually appear in the product pages.

To access the marketplace admin:

  1. Open an incognito window and go to https://woocommerce.com/my-account
  2. Log in using the WooCommerce Marketplace Admin password from 1Pass
  3. Click on "Vendor Dashboard" to see all of the plugins and their deployed versions

Manual Deploy

  • For each plugin, update date in changelog and Find & Replace the development version with the release version across all plugin files. It is a good idea to check for earlier development versions. For example, if the current dev. version is 1.2.1-dev.4 find and replace 1.2.1-dev.4, 1.2.1-dev.3, 1.2.1-dev.2, and 1.2.1-dev.1 with '1.2.2'

  • Update the date in the changelog

  • In Terminal:

     # compile and zip the plugin
 cd /path/to/wc-plugins/<plugin-dir-name>
     npx sake zip

  • Test out the plugin in the /build directory. The easiest way is to symlink the plugins in this folder to a test WordPress site

     # stage all changes
 git add -A

 # commit changes
 git commit -m "Plugin Name: x.xx.x Versioning"

 # push changes
 git push

 # copy/pasta files to Woo repo and delete all unnecessary files.

 # commit in the Woo repo
 cd path/to/woocommerce/repo
 git add -A
 git commit -m "Update Plugin Name to x.xx.x"

     # create a release in the Woo repo tagged and titled with the version (x.xx.x) and paste in the changelog entries

Tagging

Once a plugin has been finalized for release, the containing repository shall be tagged with the following format:

tag: woocommerce-plugin-name-1.0

message:

WooCommerce Plugin Name v1.0

changelog entries

Substituting the actual plugin name and version number of course. The git tag command would look like:

$ git tag -a woocommerce-plugin-name-1.0 558151a

Where 558151a is the release commit if not HEAD. Tags must then be pushed to github with the following command:

$ git push --tags

Tagging on Github.com

  1. Tag version: woocommerce-plugin-name-1.0
  2. Select the target revision
  3. Release Title: WooCommerce Plugin Name v1.0
  4. Comment: Changelog entries
  5. Attach the plugin zip as the release binary
Clone this wiki locally