search

Automattic / wc-calypso-bridge

20 stars 4 forks source link

readme

WooCommerce Calypso Bridge

This repository houses various fixes and extensions for wp-admin to enhance the experience for users of the WordPress.com Store.

Pre-Flight Checklist

Before activating master in your WordPress environment, remember to install dependencies and build all the assets:

npm install
npm run build

Note: Ensure that you currently running the required NodeJS version. Check NVM for running multiple node versions.

Deployment

IMPORTANT NOTE

Deployment steps shouldn't be followed until after the PR containing your changes has been approved and merged. Release/Deploy PRs shouldn't contain any function changes.

  1. Create a PR for your changes (bug fix, update, etc).
  2. Get a review and approval.
  3. Merge your change PR.
  4. Start following the automated deployment process below.

Automated Deployment

We now have a series of scripts that will help with automating the release process. To use these scripts, do the following.

  1. Make sure you're running NodeJS v16. If you use nvm, you can simply type nvm use. If you prefer fnm, you can run fnm use instead.
  2. Run npm install in the project root to make sure all dependencies are installed at the project level and in the ./scripts folder.
  3. Run npm run prepare-release in the project root. This will guide you through incrementing the version, updating the changelog, and creating a PR.
  4. Once that PR is approved and merged, run npm run create-release. Follow the prompts to do a build, create a new release tag, and deploy the release tag.

NOTE: Creating a new release doesn't automatically deploy the new version. A corresponding update PR will need to be opened to update the wc-calypso-bridge dependency in wpcomsh.

Manual Deployment

If, for some reason, you are unable to use the automated build/release scripts above, the process can be done manually as described below.

  1. Create a version bump pull request on wc-calypso-bridge that increments the version in composer.json, and in two spots in wc-calypso-bridge.php.

  2. Add a section to the readme.txt also with a changelog of what is in the release.

  3. Mark the pull request as ready for review, and merge once a 👍 review is given.

  4. Make sure you've closed your start script if you have it running.

  5. Back in your local copy of wc-calypso-bridge, perform the following steps:

    1. git checkout master
    2. git pull origin master
    3. nvm use in case your current node version is different
    4. npm i
    5. npm run build
    6. rm -rf node_modules so these don't get packaged up in the release

  6. Now you are ready to tag the release by replacing x.x.x with the version number being created:

    1. git tag x.x.x
    2. git checkout x.x.x
    3. git add ./build --force
    4. git commit -m 'Adding build directory to release' --no-verify
    5. git tag -f x.x.x
    6. git push origin x.x.x

  7. 🎊 Congrats, you have released a new version of wc-calypso-bridge.

NOTE: Creating a new release doesn't automatically deploy the new version. A corresponding update PR will need to be opened to update the wc-calypso-bridge dependency in wpcomsh.

Development Environment

To get started with development of front-end components run npm start.

See wp-scripts for more usage information.

Running under a local WordPress installation

To use this plugin, several conditions must be met.

Plugin Dependencies

Note that the plugin expects to find these plugins in their original folders, so renaming them may prevent the plugin from running.

Jetpack Connection & Option Values

You will need either a connected Jetpack site or use the following filter to force Jetpack into development mode:

add_filter( 'jetpack_offline_mode', '__return_true' );

For the Bridge to work, the site must have a plan. Download this gist (recommended) as a plugin and activate it.

Running on WoA

The recommended way for developing on Atomic is to have a rsync configuration in place for sending files directly into your WoA.

Contributing to The Bridge

Repository Structure

Key folders and files:

Before contributing, it's recommended to scan the includes folder in case the fix can be placed in existing controllers/files. If not, create a new file, e.g., includes/class-wc-calypso-bridge-my-custom-fix.php, and ensure that it gets included in the includes section of the main controller.

Regarding the timeline, all files under the includes folder will be loaded at plugins_loaded at 0 priority.

Here's a handy boilerplate for starting a new file in this gist.

Active Plan Detection

Plan-specific tweaks can be managed using the following global functions: Helper function Return value
wc_calypso_bridge_has_ecommerce_features() This will return true for all ecommerce-related plans (including all WordPress.com, Woo Express plans, and the Ecommerce Free Trial)
wc_calypso_bridge_is_ecommerce_plan() Returns true if the site has a paid Ecommerce plan (including all WordPress.com and Woo Express plans)
wc_calypso_bridge_is_woo_express_trial_plan() Returns true if the site has a Woo Express Trial plan.
wc_calypso_bridge_is_woo_express_performance_plan() Returns true if the site has a Woo Express Performance plan.
wc_calypso_bridge_is_woo_express_essential_plan() Returns true if the site has a Woo Express Essential plan.
wc_calypso_bridge_is_wpcom_ecommerce_plan() Returns true if the site has an Ecommerce plan from WordPress.com.
wc_calypso_bridge_is_business_plan() Returns true if the site has a business plan.

Similarly, on the JS side, use the global window.wcCalypsoBridge object for fetching information about the active plan:

Note: This list will be updated as new plans come into play.

Test Suite

This repo runs a CI process during PRs using GH Actions workflows. For now, we only run the following:

More to come in this section.