Product update guidelines and best practices

To maintain a high-quality and competitive Marketplace, we encourage all vendors to regularly update their products. Consistent updates ensure compatibility with the latest versions of WooCommerce and WordPress, improve security and performance, and deliver ongoing value to customers.

• Update your product at least every 6 months.
• Align with WooCommerce core release cycles.
• Use tools such as QIT and the Vendor Dashboard.
• Check the Feature Requests board for product ideas.
• Regular updates = better customer trust and renewal rates.

• Compatibility: Ensures your product works seamlessly with the latest WooCommerce and WordPress releases.
• Security: Patches vulnerabilities and keeps customer sites secure.
• Performance: Enhances speed, reliability, and efficiency.
• Customer Trust: Builds confidence in your brand and product longevity. Regularly updated products often see higher renewal rates. Each update is a reminder of the value of keeping a subscription.
• Support Load Reduction: Reduces the number of support tickets by proactively addressing issues.

1. Monitor the WooCommerce release calendar: Anticipate changes that might impact your product.
2. Engage customer feedback: Use reviews, support tickets, and feature requests to inform improvements, new features, and community-requested improvements.
3. Use Semantic Versioning: Example: v2.1.0 for features, v3.0.0 for breaking changes.
4. Test thoroughly: Ensure updates are stable and backward-compatible where possible. Consider integrating the QIT (Quality Insights Tool) into your workflow to automatically detect potential issues.
5. Document changes transparently: Maintain clear, customer-facing changelogs, update the documentation and the product page if needed.

Products that fail to stay current with WooCommerce core, and/or those that are not updated at least once every six months, will be flagged to be removed from the WooCommerce Marketplace.

• Major Releases: At least quarterly, to align with WooCommerce core updates.
• Security Fixes: As needed, with urgency.
• Minor Improvements: Monthly or as features and fixes are ready.
• Documentation: Keep changelogs and user guides current with each release.

Before uploading a new version of your extension, it is important to ensure that it passes all QIT quality standards. You can easily run these checks from your partner dashboard by selecting the Quality Insights menu option. To learn more about the types of tests and how to run them, please refer to the provided documentation.

You can upload the updated version after your extension passes all QIT checks.

Select the Versions tab. You’ll see all the versions you’ve previously uploaded, including highlights about what was in each version.

Select Add Version to upload an updated version, then:

• Select the .zip file you want to upload from your computer
• Add the version number
• Click Submit new version

Once submitted, we will run the following tests on the uploaded file:

• End-to-End
• Activation
• Security
• API
• PHPCompatibility Tests
• Malware Tests

All Vendor Admins will receive email notifications throughout the process, including:

• Confirmation: Vendor Admins will get an email when a new version is submitted, confirming that it is in the queue. No action is needed here.
• Rejected: If a version fails any part of our automated testing, Vendor Admins will receive an email letting them know, including the specific error. Developers should try to resolve the error and submit a new version when ready.
• Live: If a version passes automated testing, it will be automatically deployed and made available to customers. No action is needed.

Activation, Security, and Malware tests are required to pass for a new product version to be deployed.

Formatting the changelog

Read more about the changelog formatting and the changelog entry types in the developer docs for extensions.

Common errors

If an upload fails, there are a few common errors you should check first.

• The name of the file: WooCommerce.com looks for a specific name for your .zip file and the main folder within it. You’ll see the expected name when you try to upload a product:

• A changelog is present: A file named changelog.txt must be present to serve as a record of what’s changed from version to version.
• Invalid changelog: The changelog.txt provided does not match the expected format.
• Mismatch version header: The version in the plugin header doesn’t match the version provided during the upload process.
• Mismatch version: The version in the plugin header and the changelog.txt don’t match.

Viewing Test Results

The results from the automated tests will be in the Submission Tests table, which can be viewed by clicking the associated ‘View’ link identified in the image below.

To deploy a plugin programmatically, it must be a plugin update and not a new submission. This method serves as an alternative to logging into the vendor dashboard and using the UI to perform the same action.

curl -X POST https://woocommerce.com/wp-json/wc/submission/runner/v1/product/deploy \
  -F "file=@/path/to/zip" \
  -F "product_id=<product_id>" \
  -F "username=<username>" \
  -F "password=<app_password>" \
  -F "version=<product_version>"

curl -X POST https://woocommerce.com/wp-json/wc/submission/runner/v1/product/deploy/status \
  -F "product_id=<product_id>" \
  -F "username=<username>" \
  -F "password=<app_password>"

{
  "status": "queued",
  "version": "1.0.0",
  "test_runs": {
    "12345": {
      "test_run_id": "12345",
      "status": "success",
      "test_type": "activation",
      "result_url": "https://qit.woo.com/?qit_results=12345"
    },
    "67890": {
      "test_run_id": "67890",
      "status": "success",
      "test_type": "api",
      "result_url": "https://qit.woo.com/?qit_results=67890"
    }
    ...
  }
}

We strongly encourage the contribution of E2E tests for your extensions built on top of the Quality Insights Toolkit(QIT) custom E2E testing framework . By sharing these tests with us, you play a crucial role in ensuring true compatibility across different WordPress and WooCommerce versions, various PHP environments, and alongside other popular extensions. Our Custom E2E testing framework, equipped with a dockerized development environment and easy-to-use command tools, empowers you to design and execute comprehensive tests using Playwright that are tailored to your plugin’s unique functionalities.

Not only does this initiative help mitigate potential compatibility issues before they affect users, but it also enhances the overall reliability of the products within our marketplace. Participating in this process not only contributes to a robust ecosystem but also elevates your extension’s reputation for quality and reliability. Please visit the QIT Custom Test documentation to begin leveraging the power of custom tests to guarantee your extension works seamlessly in real-world scenarios and stands out in the competitive marketplace.

Feel free to reach out to the Marketpalce team for update planning, QIT help, or deployment issues.

Let’s work together to keep the Marketplace innovative, secure, and reliable for everyone.