Add documentation for code quality tools and standards

This commit is contained in:
2025-04-21 03:58:18 +01:00
parent 04cdd49a3f
commit 497c44c3c6
8 changed files with 738 additions and 1 deletions

View File

@@ -202,6 +202,8 @@ This plugin follows the [WordPress CSS Coding Standards](https://developer.wordp
This plugin uses automated tools to enforce coding standards:
### Local Development Tools
1. **PHP_CodeSniffer (PHPCS)**: Checks PHP code against the WordPress Coding Standards
```bash
composer run phpcs
@@ -222,6 +224,60 @@ This plugin uses automated tools to enforce coding standards:
npm run lint:css
```
### Continuous Integration Tools
This project integrates with several code quality tools that automatically analyze your code when you create a pull request. These tools are free for public repositories and should be integrated into any new repositories based on this template.
1. **CodeRabbit**: AI-powered code review tool
- Provides automated feedback on pull requests
- Identifies potential issues and suggests improvements
- [Website](https://www.coderabbit.ai/)
2. **CodeFactor**: Continuous code quality monitoring
- Provides a grade for your codebase
- Identifies issues related to code style, complexity, and potential bugs
- Tracks code quality over time
- [Website](https://www.codefactor.io/)
3. **Codacy**: Code quality and static analysis
- Provides a grade for your codebase
- Identifies issues related to code style, security, and performance
- Tracks code quality over time
- [Website](https://www.codacy.com/)
4. **SonarCloud**: Code quality and security analysis
- Provides detailed analysis of code quality
- Identifies security vulnerabilities and technical debt
- Tracks code quality over time
- [Website](https://sonarcloud.io/)
### How to Pass Code Quality Checks
To ensure your code passes the quality checks from these tools, follow these guidelines:
1. **Run Local Checks First**
- Before pushing your code, run PHPCS and PHPCBF locally
- Fix any issues identified by these tools
2. **Address Common Issues**
- **Indentation**: Use 4 spaces for indentation (not tabs)
- **Line Length**: Keep lines under 100 characters
- **Naming Conventions**: Follow WordPress naming conventions
- **Documentation**: Add PHPDoc comments to classes, methods, and functions
- **Error Handling**: Implement proper error handling
- **Security**: Validate and sanitize input, escape output
3. **Using AI Assistants with Code Quality Tools**
- When you receive feedback from code quality tools, you can use AI assistants to help address the issues
- Copy the output from the code quality tool and paste it into your AI assistant chat
- Ask the AI to help you understand and fix the issues
- Example prompt: "I received the following feedback from [Tool Name]. Please help me understand these issues and suggest fixes: [Paste the tool output here]"
4. **Iterative Improvement**
- Address issues one at a time, starting with the most critical
- Commit and push your changes to see if they resolve the issues
- Continue this process until all issues are resolved
## Conclusion
Following these coding standards ensures that the plugin's code is consistent, readable, and maintainable. All contributors should adhere to these standards when submitting code to the project.

View File

@@ -78,6 +78,45 @@ If you want to contribute code:
- Keep pull requests focused on a single change
- Write a clear, descriptive title and description
- Reference any related issues
- Ensure your code passes the automated code quality checks (see below)
#### Code Quality Tools
This project uses several automated code quality tools to ensure high standards. These tools are free for public repositories and will automatically analyze your code when you create a pull request:
1. **CodeRabbit**: AI-powered code review tool
- [Website](https://www.coderabbit.ai/)
- Provides automated feedback on pull requests
2. **CodeFactor**: Continuous code quality monitoring
- [Website](https://www.codefactor.io/)
- Provides a grade for your codebase
3. **Codacy**: Code quality and static analysis
- [Website](https://www.codacy.com/)
- Identifies issues related to code style, security, and performance
4. **SonarCloud**: Code quality and security analysis
- [Website](https://sonarcloud.io/)
- Provides detailed analysis of code quality and security
#### Using AI Assistants with Code Quality Tools
When you receive feedback from these code quality tools, you can use AI assistants to help address the issues:
1. Copy the output from the code quality tool
2. Paste it into your AI assistant chat
3. Ask the AI to help you understand and fix the issues
4. Implement the suggested fixes
5. Commit the changes and verify that the issues are resolved
Example prompt for AI assistants:
```
I received the following feedback from [Tool Name]. Please help me understand these issues and suggest fixes:
[Paste the tool output here]
```
## Development Environment
@@ -95,6 +134,17 @@ Before submitting a pull request, make sure to run the tests:
- End-to-End Tests: `npm run test:e2e`
- Coding Standards: `npm run lint:php`
#### Code Quality Checks
To ensure your code meets the quality standards, run these commands before submitting a pull request:
- Check coding standards: `composer run phpcs`
- Fix coding standards automatically: `composer run phpcbf`
- Check JavaScript coding standards: `npm run lint:js`
- Check CSS coding standards: `npm run lint:css`
These checks will help identify and fix issues before they are caught by the automated code quality tools in the pull request process.
## Documentation
If you're adding a new feature or changing existing functionality, please update the documentation: