Skip to content

Plugin Deployment

Jump to bottom
Ashley Gibson edited this page Jul 2, 2024 · 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/main and delete the PR branch
  • Ensure you're on master / main 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="gdcorp-partners/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. Be sure to configure SSO for the token for gdcorp-partners.
  • 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. This is not required when doing a deployment for a final release.
  • 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. Be sure to configure SSO for the token for gdcorp-partners.
  • 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

Navigate to the repository directory:

cd /path/to/wp-content/plugins/<plugin-dir>

Next we'll reinstall dependencies 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).

composer install --no-dev

Next, ensure sake is up to date:

npm update sake

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

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 see a new commit in the plugin repo (https://github.com/gdcorp-partners/{plugin-slug}), which bumps the version number of the plugin. You can check this to confirm it looks okay.

When ready, you may press "Enter" or "y" to complete the upload to WooCommerce. 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. Revert the versioning commit on the plugin's repo.

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

Creating a docs issue

You will then be asked if a docs issue should be created for your release. If you select "yes", a new issue will be created in the docs repo for the plugin, which communicates to the support team that the plugin documentation should be updated based on this release.

You should select "yes" for this if the release introduces new features, or changes the way an existing one works that may impact the documentation.

Watch for confirmation

For each plugin you deploy, you'll see a notification in #mwc-announcements 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
    • Could not get release issue: HttpError: Resource protected by organization SAML enforcement. You must grant your Personal Access token access to an organization within this enterprise. - You have not configured SSO for your GitHub API key.
    • 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

If you do get an error and need to try again, be sure to follow these steps:

  1. Revert the versioning commit in the plugin's repository. This is the commit that the sake task will have done for you during this process. (If it doesn't exist yet, then that's fine.)
  2. Then you can run the deploy again.

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