Add Compat Checker library for versioning and compatibility checks

[ibndawood]

Changes proposed in this Pull Request:

Closes #75.

This PR:

• Adds a new PHP package called compat-checker that can be installed via composer in WooCommerce Grow extensions.
• This new package runs compatibility checks based on the plugin's header file.
• Here is a list of compatibility checks run:
  • Checks if the WooCommerce plugin is installed and active.
  • Checks if the active WooCommerce version meets the minimum WooCommerce version defined in the plugin header.
  • Displays a warning if the active WooCommerce version is behind L-N (2 is the default) version.
  • Displays a warning if the active WooCommerce is untested with the plugin.
  • Displays a warning if the current WordPress version is untested with the plugin.

Detailed test instructions:

Setting up the fork.

1. Open the WooCommerce Grow repository from the URL: https://github.com/woocommerce/grow
2. On the top right, click the Fork button to fork your own copy.
3. Ensure the Copy the trunk branch only is unchecked.
4. Click the Create Fork button. This step will create a fork of woocommerce/grow. Let's say: ibndawood/grow
5. In the forked repository, create a new PR to merge the branch add/compat-checker branch into trunk.
6. Merge the PR.

Testing the GitHub Workflow

1. Navigate to Actions tab in the forked repository.
2. Ensure Public Compat Checker package workflow is added.
3. Ensure there is a branch named compat-checker.
4. Make a simple commit to the trunk to trigger the workflow.
5. Ensure the subdirectory packages/php/compat-checker contents are published into the compat-checker branch.

Including the library in the WooCommerce Extension

1. Clone any one of the WooCommerce Grow extensions. Let's say: WooCommerce Brands
2. Include the compat-checker package by adding the repository to the composer.json of the cloned repository like in the snippet below. Replace https://github.com/ibndawood/grow with the URL of your fork:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/ibndawood/grow"
    }
],
"require": {
    "woocommerce/grow": "dev-compat-checker"
},

3. Run composer update to included woocommerce/grow in the plugin's vendor folder.
4. Ensure the vendor folder has the woocommerce/grow folder.
5. Ensure the vendor/composer/autoload_psr4.php file has Automattic\WooCommerce\Grow\Tools\ namespace included.

Testing compatibility and versioning

Setup

In the main plugin file, run Automattic\WooCommerce\Grow\Tools\CompatChecker\v0_0_1\Checker::instance()->is_compatible( __FILE__, $plugin_version ) to check for compatibility and versioning. The snippet should be placed before initialising the plugin. The below example snippet is for WooCommerce Brands:

require __DIR__ . '/vendor/autoload.php';
use Automattic\WooCommerce\Grow\Tools\CompatChecker\v0_0_1\Checker;

// Plugin init hook.
add_action( 'plugins_loaded', 'wc_brands_init', 1 );

/**
 * Initialize plugin.
 */
function wc_brands_init() {
    define( 'WC_BRANDS_VERSION', '1.6.56' ); // WRCS: DEFINED_VERSION.

    if ( ! Checker::instance()->is_compatible( __FILE__, WC_BRANDS_VERSION ) ) {
	return;
    }
    // Continue with initializing...
}

WooCommerce activation tests

With the above code snippets in place, run the following tests. The instructions are for WooCommerce Brands but can be used for other WooGrow Extensions.

1. Install and activate WooCommerce Brands without installing WooCommerce.
2. Deactivate WooCommerce.
3. Verify the notice WooCommerce Brands requires WooCommerce to be installed and activated. Please install WooCommerce. is displayed.
4. Install WooCommerce without activating.
5. Verify the notice WooCommerce Brands requires WooCommerce to be activated. Please activate WooCommerce. is displayed.

WooCommerce versioning tests

⚠️ Important note: You will need to erase the transient _transient_wc_grow_compat_checker_[EXTENSION].php[VERSION after each change!!

1. Install and activate WooCommerce.
2. Install and activate WooCommerce Brands.
3. Modify the WC requires at least header field and set it to a version higher than the active WooCommerce version. Let's say the WC requires at least is set to 8.2 and the active WooCommerce version is 8.0.2.
4. Verify the notice WooCommerce Brands requires WooCommerce version 8.2 or higher. Please update WooCommerce to the latest version, or download the minimum required version is displayed.
5. Modify the WC tested up to and set it to a lower version than the active WooCommerce version. Let's say the WC tested up to is set to 7.8, the active WooCommerce version is 8.0.2 and WooCommerce Brands version is 1.6.56.
6. Verify the warning notice WooCommerce Brands - 1.6.56 is untested with WooCommerce 8.0.2 is displayed.

L2 support recommendation notice

1. Download the latest minus three WooCommerce version and activate it. Let's say 7.6.
2. Verify the warning notice Heads up! WooCommerce Brands will soon discontinue support for WooCommerce 7.6. Please update WooCommerce to take advantage of the latest updates and features.

WordPress versioning tests

⚠️ Important note: You will need to erase the transient _transient_wc_grow_compat_checker_[EXTENSION].php[VERSION after each change!!

1. Modify the Tested up to and set it to a lower version than the current WordPress version. Let's say the Tested up to is set to 6.2, the active WordPress version is 6.3, and the WooCommerce Brands version is 1.6.56.
2. Verify the warning notice WooCommerce Brands - 1.6.56 is untested with WordPress 6.3 is displayed.

Changelog entry

Add - Compat Checker library for versioning and compatibility checks.

[ibndawood]

I've added caching for get_file_data and limited check_wc_upgrade_recommendation to backend only.

[ibndawood]

@mikkamp, @budzanowski - Resolved versioning issues by adding the version information to the namespace.

[layoutd]

😮 This is very cool! Thank you for the extremely detailed testing instructions. The tests worked well with Brands and Product Filters, although I did discover that I had to delete the transients repeatedly once I started changing the versions in the header.

I added a handful of comments, mostly about links and notice settings.

[layoutd]

❓ Should the merchant be able to dismiss this error? Otherwise it just hangs out until the plugin is updated to support my WooCommerce version (good thing always on top of compatibility releases!!)

[ibndawood]

I've made the warning notice dismissible in this commit: c8c50e0

The is-dismissible applies only on the current screen. To maintain the notice state, we'll have to store the notice state in the user meta data. Do you want me to implement that?

[layoutd]

Hmm ... I guess for WooCommerce it's not particularly critical because our extensions should always be up to date with WooCommerce. We could either make it dismissible until the next WooCommerce update, or leave as is and then change it if we see that our extensions are falling behind on compatibility (+1 technical debt)

[ibndawood]

Thank you, @layoutd, for taking the time to review this PR. I'll go through your feedback and shall add my comments/fixes.

[ibndawood]

Hello again, @layoutd. Thank you for taking the time to review this PR. I've made the changes you suggested. This is ready for another round of review. I've also added a question related to the dismiss notice. Please let me know what you think.

[layoutd]

LGTM - the changes work well and I think this is OK as is. I still have a few more comments though (😳)

• There's a bit of a hiccup in the "Install WooCommerce" link process, where the prompt to install the plugin appears on the page where I just installed the plugin:
  
  I wonder if that check could be skipped on that page in particular? But it's not a big deal since it ends up resolving itself, just could be a bit confusing.
• I added some notes to the testing instructions as a reminder that that the compatibility transient needs to be erased for version testing.
• I wonder if this text should just be WooCommerce Brands version 1.6.58 … or WooCommerce Brands - version 1.6.58 … .
  

[ibndawood]

I wonder if that check could be skipped on that page in particular? But it's not a big deal since it ends up resolving itself, just could be a bit confusing.

I agree. I'll fix this.

I added some notes to the testing instructions as a reminder that that the compatibility transient needs to be erased for version testing.

Thank you.

I wonder if this text should just be WooCommerce Brands version 1.6.58 … or WooCommerce Brands - version 1.6.58 …

I'd go with WooCommerce Brands - version 1.6.58.

[ibndawood]

Hey @layoutd, I've addressed the below comment in a8579b7:

I wonder if that check could be skipped on that page in particular? But it's not a big deal since it ends up resolving itself, just could be a bit confusing.

In e7bf974, I've set the text in the notice like this: WooCommerce Brands - version 1.6.58.

I'd like you to take a look at these two changes and let me know your feedback.

[layoutd]

Nice! Both "issues" look like they've been solved, thanks for humoring me @ibndawood!

[ibndawood]

Thank you, @layoutd, for your time to review the final changes. I'll merge this PR to the trunk.