Docs: Adding Best Practices for Compatibility, Maintainability, Privacy Standards, Support and Documentation (#47976)
Adding quality+best practices docs
This commit is contained in:
Brent MacKinnon
GitHub
parent
4bee1547b7
commit
0606b9580b
|
|
@ -705,6 +705,15 @@
|
|||
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/quality-and-best-practices/writing-high-quality-testing-instructions.md",
|
||||
"id": "56a8ef0ef0afec9c884f655e7fdd23d9666c9d00"
|
||||
},
|
||||
{
|
||||
"post_title": "Support and documentation for WooCommerce extensions",
|
||||
"menu_title": "Support and documentation",
|
||||
"tags": "reference",
|
||||
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/quality-and-best-practices/support-and-documentation.md",
|
||||
"hash": "48ec15e8c50c2fceea0bce267a52dcd7c740a9f1614773b10b6bab4a2e605a8c",
|
||||
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/quality-and-best-practices/support-and-documentation.md",
|
||||
"id": "c7ab700f5ab812a79b646a865caf429864becdb8"
|
||||
},
|
||||
{
|
||||
"post_title": "Understanding the risks of removing URL bases in WooCommerce",
|
||||
"menu_title": "Risks of removing URL bases",
|
||||
|
|
@ -714,6 +723,18 @@
|
|||
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/quality-and-best-practices/removing-product-product-category-or-shop-from-the-url.md",
|
||||
"id": "827bfa56d40c2155542147ea5afe7cc756e18c5d"
|
||||
},
|
||||
{
|
||||
"post_title": "Privacy Standards for WooCommerce Extensions",
|
||||
"menu_title": "Privacy Standards",
|
||||
"tags": "reference",
|
||||
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/quality-and-best-practices/privacy-standards.md",
|
||||
"hash": "44496b3d6244ea09c86b9d13fbefe9b77478311df25def6ae5e4e567a0e2bd6f",
|
||||
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/quality-and-best-practices/privacy-standards.md",
|
||||
"id": "840cf3001ed520ed206a42b147a2e3afa4ed82ae",
|
||||
"links": {
|
||||
"./gdpr-compliance.md": "af392a92b41b69b543c5ec77a07af770f6bb1587"
|
||||
}
|
||||
},
|
||||
{
|
||||
"post_title": "How to optimize performance for WooCommerce stores",
|
||||
"menu_title": "Optimize store performance",
|
||||
|
|
@ -735,6 +756,15 @@
|
|||
"./css-sass-naming-conventions.md": "a34404f72868f2780ccf07da9b998204b8213d32"
|
||||
}
|
||||
},
|
||||
{
|
||||
"post_title": "Maintaining and updating WooCommerce extensions",
|
||||
"menu_title": "Maintainability and updates",
|
||||
"tags": "reference",
|
||||
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/quality-and-best-practices/maintainability.md",
|
||||
"hash": "6c1afab52dfab6998b87c4fac3acaba05ef516c4ff483b1ad46be13bc1b299c1",
|
||||
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/quality-and-best-practices/maintainability.md",
|
||||
"id": "828687b931d51c041ff4b4e0dc9a3a5b832b7ead"
|
||||
},
|
||||
{
|
||||
"post_title": "WooCommerce grammar, punctuation and capitalization guide",
|
||||
"menu_title": "Grammar, punctuation and capitalization",
|
||||
|
|
@ -769,12 +799,21 @@
|
|||
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/quality-and-best-practices/core-critical-flows.md",
|
||||
"id": "e561b46694dba223c38b87613ce4907e4e14333a"
|
||||
},
|
||||
{
|
||||
"post_title": "Compatibility and interoperability for WooCommerce extensions",
|
||||
"menu_title": "Compatibility best practices",
|
||||
"tags": "reference",
|
||||
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/quality-and-best-practices/compatibility.md",
|
||||
"hash": "c8e09923cffd4a3951dfc2db43823f9d469439775019104f687aa2c95caff142",
|
||||
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/quality-and-best-practices/compatibility.md",
|
||||
"id": "e3353f3e7a61bfd0f839d74c5baee2847b4b75d0"
|
||||
},
|
||||
{
|
||||
"post_title": "WooCommerce coding standards",
|
||||
"menu_title": "Coding standards",
|
||||
"tags": "reference",
|
||||
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/quality-and-best-practices/coding-standards.md",
|
||||
"hash": "f23b9ab30de8af1356e92999d492ddb5bfb1303e88e64c4e58a26fbc9b93e6d4",
|
||||
"hash": "7c5b8a0b555f81606fd6d2c85f62a00feaff369569666ba88d029fd384202f2f",
|
||||
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/quality-and-best-practices/coding-standards.md",
|
||||
"id": "b09a572b8a452b6cd795e0985daa85f06e5889fb"
|
||||
}
|
||||
|
|
@ -1266,5 +1305,5 @@
|
|||
"categories": []
|
||||
}
|
||||
],
|
||||
"hash": "fe317e6e18998dd7e1936581791d6e949ff59137cd42d5004464093efbca1a88"
|
||||
"hash": "4b21f13102730165225dfb14ca0e448f66be236867a000e807d4b5327ec02aa5"
|
||||
}
|
||||
|
|
@ -4,11 +4,14 @@ menu_title: Coding standards
|
|||
tags: reference
|
||||
---
|
||||
|
||||
## Position of hooks
|
||||
Adhering to WooCommerce coding standards is essential for maintaining high code quality, ensuring compatibility, and facilitating easier maintenance and updates. This document outlines the recommended coding practices for developers working within the WooCommerce ecosystem, including the use of hooks, function prefixing, translatable texts, and code structure.
|
||||
|
||||
Position hooks below the function call, as this follows the common pattern in the WordPress and WooCommerce ecosystem.
|
||||
|
||||
### Example
|
||||
## Position of Hooks
|
||||
|
||||
Position hooks below the function call to align with the common pattern in the WordPress and WooCommerce ecosystem.
|
||||
|
||||
Example:
|
||||
|
||||
```php
|
||||
/**
|
||||
|
|
@ -22,9 +25,9 @@ add_action( 'wp_footer', 'YOUR_PREFIX_custom_message' );
|
|||
|
||||
## Prefixing function calls
|
||||
|
||||
Use a consistent prefix for all function calls. For the code snippets in this repo, use the prefix `YOUR_PREFIX`.
|
||||
Use a consistent prefix for all function calls to avoid conflicts. For the code snippets in this repo, use `YOUR_PREFIX`.
|
||||
|
||||
### Example
|
||||
Example:
|
||||
|
||||
```php
|
||||
/**
|
||||
|
|
@ -38,13 +41,13 @@ add_filter( 'woocommerce_product_get_price', 'YOUR_PREFIX_custom_discount', 10,
|
|||
|
||||
## Translatable texts and text domains
|
||||
|
||||
Make all plain texts translatable, and use a consistent text domain. This aligns with the best practices for internationalisation. For the code snippets in this repo, use the textdomain `YOUR-TEXTDOMAIN`.
|
||||
Ensure all plain texts are translatable and use a consistent text domain, adhering to internationalization best practices. For the code snippets in this repo, use the textdomain `YOUR-TEXTDOMAIN`.
|
||||
|
||||
### Example
|
||||
Example:
|
||||
|
||||
```php
|
||||
/**
|
||||
* Add custom message.
|
||||
* Add welcome message.
|
||||
*/
|
||||
function YOUR_PREFIX_welcome_message() {
|
||||
echo __( 'Welcome to our website', 'YOUR-TEXTDOMAIN' );
|
||||
|
|
@ -54,9 +57,9 @@ add_action( 'wp_footer', 'YOUR_PREFIX_welcome_message' );
|
|||
|
||||
## Use of function_exists()
|
||||
|
||||
Wrap all function calls in a `function_exists()` call to prevent errors due to potential function redeclaration.
|
||||
To prevent errors from potential function redeclaration, wrap all function calls with `function_exists()`.
|
||||
|
||||
### Example
|
||||
Example:
|
||||
|
||||
```php
|
||||
/**
|
||||
|
|
@ -69,3 +72,26 @@ if ( ! function_exists( 'YOUR_PREFIX_theme_setup' ) ) {
|
|||
}
|
||||
add_action( 'after_setup_theme', 'YOUR_PREFIX_theme_setup' );
|
||||
```
|
||||
|
||||
## Code Quality Standards
|
||||
|
||||
To ensure the highest standards of code quality, developers are encouraged to adhere to the following practices:
|
||||
|
||||
### WooCommerce Sniffs and WordPress Code Standards
|
||||
|
||||
- **Ensure no code style issues** when code is passed through WooCommerce Sniffs and WordPress Code Standards for PHP_CodeSniffer.
|
||||
|
||||
### Automated Testing
|
||||
|
||||
- **Unit Tests**: Implement automated unit tests to validate code functionality in isolation.
|
||||
- **E2E Tests**: Utilize automated end-to-end tests to verify the integrated operation of components within the application.
|
||||
|
||||
### Tracking and Managing Bugs
|
||||
|
||||
- **Monitor and aim to minimize** the number of open bugs, ensuring a stable and reliable product.
|
||||
|
||||
### Code Organization
|
||||
|
||||
- **Organize code in self-contained classes** to avoid creating "god/super classes" that contain all plugin code. This practice promotes modularity and simplifies maintenance.
|
||||
|
||||
By following these coding standards and practices, developers can create high-quality, maintainable, and secure WooCommerce extensions that contribute positively to the WordPress ecosystem.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
post_title: Compatibility and interoperability for WooCommerce extensions
|
||||
menu_title: Compatibility best practices
|
||||
tags: reference
|
||||
---
|
||||
|
||||
Ensuring your WooCommerce extension is compatible and interoperable with the core platform, various components, and other extensions is fundamental to providing a seamless experience for users. This document covers the importance of compatibility, the process for self-declared compatibility checks, manual testing for compatibility issues, and troubleshooting common problems.
|
||||
|
||||
## Compatibility importance
|
||||
|
||||
Compatibility ensures that your extension works as expected across different environments, including various versions of WordPress and WooCommerce, as well as with other plugins and themes. Ensuring compatibility is crucial for:
|
||||
|
||||
- **User experience**: Preventing conflicts that can lead to functionality issues or site downtime.
|
||||
- **Adoption and retention**: Users are more likely to install and keep updates if they're assured of compatibility.
|
||||
- **Security and performance**: Compatible extensions are less likely to introduce vulnerabilities or degrade site performance.
|
||||
|
||||
## Self-declared compatibility checks
|
||||
|
||||
Developers should declare their extension's compatibility with the latest versions of WordPress and WooCommerce, as well as with specific components like Cart & Checkout blocks, High Performance Order Storage (HPOS), Product Editor, and Site Editor. This process involves:
|
||||
|
||||
1. **Testing**: Before release, thoroughly test the extension with the latest versions of WordPress and WooCommerce, as well as the specified components.
|
||||
2. **Declaration**: Update the extension's documentation and metadata to reflect its compatibility with these platforms and components.
|
||||
3. **Communication**: Inform users of the compatible versions in the extension's change log, website, or repository.
|
||||
|
||||
## Manual Compatibility Testing
|
||||
|
||||
Manual testing is essential to identify and resolve potential compatibility issues. Follow these steps for effective manual compatibility testing:
|
||||
|
||||
1. **Set up a testing environment** that mirrors a typical user setup, including the latest versions of WordPress and WooCommerce.
|
||||
2. **Test with Core components**: Verify the extension's functionality with core components like Cart & Checkout blocks, HPOS, Product Editor, and Site Editor.
|
||||
3. **Cross-plugin compatibility**: Activate your extension alongside other commonly used plugins to check for conflicts.
|
||||
4. **Theme compatibility**: Test your extension with several popular themes to ensure it works correctly and maintains a consistent appearance.
|
||||
|
||||
## Troubleshooting and resolving compatibility issues
|
||||
|
||||
Despite thorough testing, compatibility issues may arise. Here are common problems and steps to resolve them:
|
||||
|
||||
### Conflicts with other extensions
|
||||
|
||||
- **Diagnosis**: Use tools like [Health Check & Troubleshooting plugin](https://wordpress.org/plugins/health-check/) to identify conflicting plugins.
|
||||
- **Resolution**: Contact the other plugin's developer for collaboration, or implement conditional logic in your extension to avoid the conflict.
|
||||
|
||||
### Theme Compatibility Issues
|
||||
|
||||
- **Diagnosis**: Check for styling or layout issues when your extension is used with different themes.
|
||||
- **Resolution**: Use more generic CSS selectors and provide configuration options for better theme integration.
|
||||
|
||||
### Updates Breaking Compatibility
|
||||
|
||||
- **Preventive Measures**: Subscribe to the [WooCommerce developer blog](https://developer.woocommerce.com) to stay informed about upcoming changes.
|
||||
- **Quick Fixes**: Prepare patches or minor updates to address compatibility issues as soon as possible after a core update.
|
||||
|
||||
### No Errors with Multiple Extensions Activated
|
||||
|
||||
- **Best Practice**: Regularly test your extension in a multi-plugin environment to ensure it does not cause or suffer from conflicts.
|
||||
|
||||
## Conclusion
|
||||
|
||||
Maintaining compatibility and interoperability is a continuous effort that requires regular testing, updates, and communication with your users and the broader developer community. By following these guidelines, you can enhance the reliability, user satisfaction, and success of your WooCommerce extension.
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
post_title: Maintaining and updating WooCommerce extensions
|
||||
menu_title: Maintainability and updates
|
||||
tags: reference
|
||||
---
|
||||
|
||||
Maintaining and updating WooCommerce extensions is crucial for ensuring they remain compatible, secure, and functional within the ever-evolving WordPress ecosystem. This document outlines best practices for ensuring easy maintainability, adhering to update frequency and process, and conducting manual update checks.
|
||||
|
||||
## Ensuring Easy Maintainability
|
||||
|
||||
Maintainable code is essential for the long-term success of any WooCommerce extension. It ensures that your extension can be easily updated, debugged, and extended, both by you and others in the future.
|
||||
|
||||
### Importance of Writing Maintainable Code
|
||||
|
||||
- **Future-proofing**: Maintainable code helps in adapting to future WooCommerce and WordPress updates.
|
||||
- **Collaboration**: Makes it easier for teams to work together on the extension.
|
||||
- **Cost-effective**: Reduces the time and resources required for adding new features or fixing issues.
|
||||
|
||||
### Strategies to Achieve Maintainability
|
||||
|
||||
- **Modular Code**: Break down your extension into smaller, focused modules or components.
|
||||
- **Coding Standards**: Follow the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/) to ensure consistency.
|
||||
- **Documentation**: Document your code extensively to explain "why" behind the code, not just "how" to use it.
|
||||
- **Refactoring**: Regularly refactor your code to improve its structure without altering the external behavior.
|
||||
|
||||
## Update Frequency and Process
|
||||
|
||||
Keeping your extension up-to-date is vital for security, compatibility, and performance. Regular updates also signal to users that the extension is actively maintained.
|
||||
|
||||
### Best Practices for Regular Updates
|
||||
|
||||
- **Scheduled Updates**: Plan regular updates (e.g., monthly) to incorporate bug fixes, security patches, and new features.
|
||||
- **Version Control**: Use version control systems like Git to manage changes and collaborate efficiently.
|
||||
- **Compatibility Checks**: Before releasing an update, thoroughly test your extension with the latest versions of WordPress and WooCommerce to ensure compatibility.
|
||||
- **Changelogs**: Maintain clear changelogs for each update to inform users about new features, fixes, and changes.
|
||||
|
||||
### Recommended Update Frequency
|
||||
|
||||
- We recommend that extensions receive an update **at least once every 30 days**. This frequency ensures that extensions can quickly adapt to changes in WooCommerce, WordPress, or PHP, and address any security vulnerabilities or bugs.
|
||||
|
||||
## Manual Update Checks
|
||||
|
||||
While automated update systems like the WordPress Plugin Repository offer a way to distribute updates, developers should also have a process for manually tracking and managing updates.
|
||||
|
||||
### How Developers Can Manually Track and Manage Updates
|
||||
|
||||
- **User Feedback**: Monitor forums, support tickets, and user feedback for issues that may require updates.
|
||||
- **Security Monitoring**: Stay informed about the latest security vulnerabilities and ensure your extension is not affected.
|
||||
- **Performance Testing**: Regularly test your extension for performance and optimize it in updates.
|
||||
- **Compatibility Testing**: Manually test your extension with beta releases of WordPress and WooCommerce to anticipate compatibility issues before they arise.
|
||||
|
||||
## Conclusion
|
||||
|
||||
Maintainability and regular updates are key to the success and longevity of WooCommerce extensions. By writing maintainable code, adhering to a consistent update process, and actively monitoring the extension's performance and compatibility, developers can ensure their products remain valuable and functional for users over time.
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
---
|
||||
post_title: Privacy Standards for WooCommerce Extensions
|
||||
menu_title: Privacy Standards
|
||||
tags: reference
|
||||
---
|
||||
|
||||
Privacy and data protection are becoming increasingly important online, and WooCommerce extensions are no exception. This document outlines the key markers of quality regarding privacy for WooCommerce extensions, the current methods for testing compliance, and the standards developers should adhere to ensure user trust and legal compliance.
|
||||
|
||||
## Standards for privacy
|
||||
|
||||
To maintain high privacy standards, developers of WooCommerce extensions should adhere to the following:
|
||||
|
||||
### Presence of privacy policy page
|
||||
|
||||
- A privacy policy should be readily available and easy to understand. It must clearly describe the types of data collected by the extension, the purpose of data collection, how data is processed and stored, and the users' rights concerning their data.
|
||||
|
||||
### No unauthorized external requests
|
||||
|
||||
- All resources required by the extension should be hosted within the plugin folder/zip file unless there's a clear, justified reason for external requests, which should then be disclosed in the privacy policy.
|
||||
- Unauthorized or undisclosed external requests, especially those that could expose user data to third-party services without consent, are strictly against privacy standards.
|
||||
|
||||
### GDPR compliance
|
||||
|
||||
For guidance on ensuring your WooCommerce extension complies with the General Data Protection Regulation (GDPR), please refer to our detailed documentation on [GDPR compliance](./gdpr-compliance.md).
|
||||
|
||||
## Conclusion
|
||||
|
||||
Adhering to privacy standards is essential for WooCommerce extension developers to build trust with users and ensure compliance with legal requirements. By establishing a clear privacy policy and avoiding unauthorized external requests, developers can demonstrate their commitment to privacy and data protection. Regular testing and compliance checks will help maintain these standards and protect user data effectively.
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
post_title: Support and documentation for WooCommerce extensions
|
||||
menu_title: Support and documentation
|
||||
tags: reference
|
||||
---
|
||||
|
||||
Effective support and comprehensive documentation are fundamental to the success of any WooCommerce extension. They not only enhance the user experience but also facilitate easier maintenance and development. This document outlines the best practices for creating documentation, providing support, and establishing feedback mechanisms.
|
||||
|
||||
## Creating effective documentation
|
||||
|
||||
Good documentation serves as a guide, helping users understand and utilize your extension to its full potential. It can significantly reduce the volume of support requests by answering common questions and troubleshooting typical issues.
|
||||
|
||||
### Importance of good documentation
|
||||
|
||||
- **User Autonomy**: Allows users to solve problems independently.
|
||||
- **Reduced Support Load**: Comprehensive documentation can answer many user questions, reducing the need for direct support.
|
||||
- **Improved User Satisfaction**: Users are more satisfied with the product when they can easily find information.
|
||||
|
||||
### How to create effective documentation
|
||||
|
||||
- **User-friendly language**: Write in clear, simple language accessible to users of all skill levels.
|
||||
- **Comprehensive coverage**: Cover all features of your extension, including setup, configuration, troubleshooting, and FAQs.
|
||||
- **Accessibility**: Ensure documentation is easy to navigate with a clear structure and search functionality.
|
||||
- **Regular updates**: Keep the documentation up to date with the latest version of the extension.
|
||||
|
||||
### Standards for documentation
|
||||
|
||||
- **Presence of public documentation**: Ensure that users have access to basic documentation that covers essential information about the extension.
|
||||
- **Quality of public documentation**: Documentation should be clear, concise, and free of technical jargon.
|
||||
- **Developer-oriented documentation**: Provide detailed documentation aimed at developers who wish to extend or integrate with your extension.
|
||||
- **Advanced internal documentation**: Maintain in-depth documentation for internal use, covering complex features and developer notes.
|
||||
|
||||
## Providing support
|
||||
|
||||
Offering timely and effective support is crucial for resolving user issues and maintaining a positive reputation.
|
||||
|
||||
### Best practices for offering support
|
||||
|
||||
- **Service level agreements (SLA)**: Establish clear SLAs for response times to manage user expectations.
|
||||
- **Knowledgeable staff**: Ensure your team is well-trained and familiar with the extension and common issues.
|
||||
- **Proactive support**: Monitor for common issues and reach out to users who might be affected.
|
||||
|
||||
### Standards for support
|
||||
|
||||
- **Support - SLA**: Define an SLA for how quickly support requests will be acknowledged and resolved.
|
||||
- **Support quality**: Regularly review support interactions to ensure quality, accuracy, and helpfulness.
|
||||
|
||||
## Feedback Mechanisms
|
||||
|
||||
Feedback is invaluable for continuous improvement of your extension and support services.
|
||||
|
||||
### How to establish and utilize feedback channels
|
||||
|
||||
- **Surveys and feedback forms**: Implement post-support surveys and feedback forms on your documentation pages.
|
||||
- **Community forums**: Engage with users on community forums where they can share feedback, ask questions, and offer suggestions.
|
||||
- **Social media and email**: Encourage feedback through social media channels and support emails.
|
||||
|
||||
### Utilizing feedback to improve
|
||||
|
||||
- **Act on feedback**: Regularly review feedback to identify areas for improvement in your extension and support services.
|
||||
- **Update documentation**: Use feedback to fill gaps in your documentation and clarify existing content.
|
||||
- **Train support staff**: Use common questions and feedback to train your support staff and improve their knowledge base.
|
||||
|
||||
## Conclusion
|
||||
|
||||
Support and documentation are critical components of the overall user experience for WooCommerce extensions. By investing in high-quality documentation, providing excellent support, and actively seeking and utilizing user feedback, developers can enhance user satisfaction, reduce support workload, and continuously improve their extensions.
|
||||
Loading…
Reference in New Issue