Skip to content

Build & Release

Jump to bottom
Gan Eng Chin edited this page Nov 30, 2022 · 33 revisions

Prerequisites

  • Ensure you have svn installed on your system by running which svn. For macOS, svn can be installed (if missing) using brew install svn.
  • Ensure you have Woorelease > 2.3.0 installed, along with its prerequisites and setup.

In this guide, we will assume that the Woorelease script is aliased to wr.

SVN requires the following to be present in the ~/.subversion/servers file:

[groups]
wporgplugins = plugins.svn.wordpress.org
 
[wporgplugins]
username = automattic
store-passwords = no

You will likely need to have the automattic WordPress.org password on hand for your first release.

Also be aware that, in this guide, X.X.X is used as a placeholder but should be replaced with the actual release version (e.g., 1.5.0).

Preparing the release

  1. Create a release/X.X.X branch based off develop. Copy the URL for the branch from GitHub for use later (e.g. https://github.com/woocommerce/facebook-for-woocommerce/tree/release/1.5.0)

  2. Changelog - Note that there are two ways to prepare the required changelog entries, automatically (a.) and manually (b.). Method (a.) works well with the Facebook for WooCommerce repository.

    a. Woorelease provides a --generate_changelog option that will automatically create the changelog entries in readme.txt and changelog.txt.

    • If you want to exclude some changelog entries (e.g. "Fix - Reintegrate trunk to develop"), you can find the PRs and label them with changelog: none. Re-run the changelog generation, and you won't see the entries anymore.

    b. Alternatively, you can manually ensure the readme.txt and changelog.txt files have changelog entries for the changes included in the new version (note the header formatting difference in readme.txt)

    • In the readme.txt file the heading format is = X.X.X - 2021-xx-xx =
    • In the changelog.txt file the heading format is 2021-xx-xx - version X.X.Xshould be left untouched, and will be automatically replaced during the release process.
    • Note that 2021-xx-xx should be left with the xx-xx values unfilled, as they will be automatically replaced by Woorelease.
    • You can use woorelease to generate changelog entries: 
      wr cl:generate --product_version=X.X.X https://github.com/woocommerce/facebook-for-woocommerce/tree/release/X.X.X
      If you bump WP/WC tested versions, you can add --wp_tested=5.9 --wc_tested=6.0. Copy the produced entries to the changelog.txt with the correct header.

  3. Using the URL from step 1, to automatically generate the changelog entries, run

    wr simulate --product_version=X.X.X --generate_changelog https://github.com/woocommerce/facebook-for-woocommerce/tree/release/X.X.X

    Alternatively, if you have manually prepared the changelog entries, run

    wr simulate --product_version=X.X.X https://github.com/woocommerce/facebook-for-woocommerce/tree/release/X.X.X

  4. Confirm that there are no errors generated from the simulate command.

  5. Review the generated facebook-for-woocommerce.zip package to confirm the release changes are included, the changelog entries look correct, and the version has been bumped where necessary.

Deploy

⚠️ Caution Woorelease version ≤ 2.0.4

Since the entry headings of changelog.txt are not in the usual WPORG format, using woorelease version ≤ 2.0.4 will cause an issue when deploying to WPORG. The issue has been fixed in woocommerce/woorelease#328, until it's released, please consider using woorelease 6a492b9abd379e8dc8f0e19807a39b4f6daa8720 or develop versions to avoid the issue. For example:

php woorelease.php release --product_version=X.X.X https://github.com/woocommerce/facebook-for-woocommerce/tree/release/X.X.X

To detect and fix this deployment issue after running woorelease, please refer to the After deploy section for troubleshooting instructions.

Deployment involves substituting the simulate command with the release command (with or without --update_changelog as required):

wr release --product_version=X.X.X --update_changelog https://github.com/woocommerce/facebook-for-woocommerce/tree/release/X.X.X

If you encounter an error with the SVN portion of the process, it's possible that you need to clear out the SVN cache:

rm -rf ~/.subversion/auth/

If an error occurs during the release command above due to SVN, you can re-run just the release portion:

wr wporg:release --product_version=X.X.X --release https://github.com/woocommerce/facebook-for-woocommerce/tree/release/X.X.X

After deploy

  1. Confirm the release deployed correctly to GitHub and WPORG.
    • Ensure you can download and install the latest release from WPORG and WCCOM.
    • We’ve had an issue where the release tag (e.g. 2.6.1) wasn’t present in the svn tags/ folder.
    • Troubleshooting processes when the release version doesn't exist in the svn tags/ folder:
      1. Check the version by Stable tag in https://plugins.svn.wordpress.org/facebook-for-woocommerce/trunk/readme.txt to see if the new release is committed to trunk
      2. If the above version is the same as the one just released, then you can make up the missed version tag by svn cp https://plugins.svn.wordpress.org/facebook-for-woocommerce/trunk https://plugins.svn.wordpress.org/facebook-for-woocommerce/tags/X.X.X -m "Tagging version X.X.X". Please note that the X.X.X is used as a placeholder but should be replaced with the actual release version (e.g., 1.5.0).
      3. Wait for a while, and the zip file should be able to download from: https://downloads.wordpress.org/plugin/facebook-for-woocommerce.x.x.x.zip
  2. Create the PRs to merge the release branch into trunk and develop. Label the PRs with changelog: none since they don't need to appear in future changelog generation.
  3. Close the release milestone.
  4. Publish any documentation updates relating to the release:

Clone this wiki locally