Add documentation for code quality tools and standards
This commit is contained in:
283
wiki/Coding-Standards.md
Normal file
283
wiki/Coding-Standards.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# Coding Standards
|
||||
|
||||
This document outlines the coding standards used in this plugin. Following these standards ensures consistency, readability, and maintainability of the codebase.
|
||||
|
||||
## PHP Coding Standards
|
||||
|
||||
This plugin follows the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/) with some additional guidelines.
|
||||
|
||||
### File Structure
|
||||
|
||||
- Each PHP file should begin with the PHP opening tag `<?php` (no closing tag)
|
||||
- Files should use the Unix line endings (LF)
|
||||
- Files should be encoded in UTF-8 without BOM
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- **Classes**: Use `PascalCase` for class names
|
||||
```php
|
||||
class MyClassName {}
|
||||
```
|
||||
|
||||
- **Methods and Functions**: Use `snake_case` for method and function names
|
||||
```php
|
||||
function my_function_name() {}
|
||||
public function my_method_name() {}
|
||||
```
|
||||
|
||||
- **Variables**: Use `snake_case` for variable names
|
||||
```php
|
||||
$my_variable_name = 'value';
|
||||
```
|
||||
|
||||
- **Constants**: Use `UPPERCASE_WITH_UNDERSCORES` for constants
|
||||
```php
|
||||
define('MY_CONSTANT', 'value');
|
||||
const MY_CLASS_CONSTANT = 'value';
|
||||
```
|
||||
|
||||
- **Namespaces**: Use `PascalCase` for namespace segments
|
||||
```php
|
||||
namespace WPALLSTARS\PluginStarterTemplate;
|
||||
```
|
||||
|
||||
- **Hooks**: Prefix hooks with the plugin's prefix
|
||||
```php
|
||||
do_action('wpst_hook_name');
|
||||
apply_filters('wpst_filter_name', $value);
|
||||
```
|
||||
|
||||
### Indentation and Formatting
|
||||
|
||||
- Use 4 spaces for indentation (not tabs)
|
||||
- Opening braces for classes and functions should be on the same line
|
||||
- Control structures should have one space between the statement and the opening parenthesis
|
||||
- Each line should be no longer than 100 characters
|
||||
|
||||
```php
|
||||
if ($condition) {
|
||||
// Code here
|
||||
} elseif ($another_condition) {
|
||||
// More code
|
||||
} else {
|
||||
// Default code
|
||||
}
|
||||
```
|
||||
|
||||
### Documentation
|
||||
|
||||
- All classes, methods, and functions should be documented using PHPDoc
|
||||
- Include a description, parameters, return values, and exceptions
|
||||
|
||||
```php
|
||||
/**
|
||||
* Short description of the function.
|
||||
*
|
||||
* Longer description if needed.
|
||||
*
|
||||
* @param string $param1 Description of the parameter.
|
||||
* @param int $param2 Description of the parameter.
|
||||
* @return bool Description of the return value.
|
||||
* @throws Exception When something goes wrong.
|
||||
*/
|
||||
function my_function($param1, $param2) {
|
||||
// Function code
|
||||
}
|
||||
```
|
||||
|
||||
### Object-Oriented Programming
|
||||
|
||||
- Each class should have a single responsibility
|
||||
- Use visibility declarations for all properties and methods (public, protected, private)
|
||||
- Use type hints for parameters and return types when possible
|
||||
|
||||
```php
|
||||
class MyClass {
|
||||
/**
|
||||
* Property description.
|
||||
*
|
||||
* @var string
|
||||
*/
|
||||
private $property;
|
||||
|
||||
/**
|
||||
* Method description.
|
||||
*
|
||||
* @param string $param Description of the parameter.
|
||||
* @return bool Description of the return value.
|
||||
*/
|
||||
public function my_method(string $param): bool {
|
||||
// Method code
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## JavaScript Coding Standards
|
||||
|
||||
This plugin follows the [WordPress JavaScript Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/).
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- **Variables and Functions**: Use `camelCase` for variable and function names
|
||||
```javascript
|
||||
var myVariableName = 'value';
|
||||
function myFunctionName() {}
|
||||
```
|
||||
|
||||
- **Constants**: Use `UPPERCASE_WITH_UNDERSCORES` for constants
|
||||
```javascript
|
||||
var MY_CONSTANT = 'value';
|
||||
```
|
||||
|
||||
### Indentation and Formatting
|
||||
|
||||
- Use 4 spaces for indentation (not tabs)
|
||||
- Opening braces should be on the same line as the statement
|
||||
- Each line should be no longer than 100 characters
|
||||
|
||||
```javascript
|
||||
if (condition) {
|
||||
// Code here
|
||||
} else if (anotherCondition) {
|
||||
// More code
|
||||
} else {
|
||||
// Default code
|
||||
}
|
||||
```
|
||||
|
||||
### Documentation
|
||||
|
||||
- Use JSDoc for documenting functions and objects
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Short description of the function.
|
||||
*
|
||||
* @param {string} param1 - Description of the parameter.
|
||||
* @param {number} param2 - Description of the parameter.
|
||||
* @returns {boolean} Description of the return value.
|
||||
*/
|
||||
function myFunction(param1, param2) {
|
||||
// Function code
|
||||
}
|
||||
```
|
||||
|
||||
## CSS Coding Standards
|
||||
|
||||
This plugin follows the [WordPress CSS Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/).
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- Use lowercase for selectors
|
||||
- Use hyphens to separate words in class and ID names
|
||||
- Prefix classes and IDs with the plugin's prefix
|
||||
|
||||
```css
|
||||
.wpst-container {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
#wpst-header {
|
||||
padding: 10px;
|
||||
}
|
||||
```
|
||||
|
||||
### Indentation and Formatting
|
||||
|
||||
- Use 4 spaces for indentation (not tabs)
|
||||
- Each property should be on its own line
|
||||
- Include a space after the colon in property declarations
|
||||
- End each declaration with a semicolon
|
||||
- Use single quotes for attribute selectors and property values
|
||||
|
||||
```css
|
||||
.wpst-container {
|
||||
margin: 0;
|
||||
padding: 10px;
|
||||
font-family: 'Helvetica', sans-serif;
|
||||
}
|
||||
```
|
||||
|
||||
## Automated Code Checking
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
2. **PHP Code Beautifier and Fixer (PHPCBF)**: Automatically fixes some coding standard violations
|
||||
```bash
|
||||
composer run phpcbf
|
||||
```
|
||||
|
||||
3. **ESLint**: Checks JavaScript code against the WordPress Coding Standards
|
||||
```bash
|
||||
npm run lint:js
|
||||
```
|
||||
|
||||
4. **Stylelint**: Checks CSS code against the WordPress Coding Standards
|
||||
```bash
|
||||
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.
|
||||
180
wiki/Contributing.md
Normal file
180
wiki/Contributing.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# Contributing
|
||||
|
||||
Thank you for considering contributing to this project! This document provides guidelines and instructions for contributing.
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
By participating in this project, you agree to abide by our code of conduct:
|
||||
|
||||
- Be respectful and inclusive
|
||||
- Be patient and welcoming
|
||||
- Be considerate
|
||||
- Be collaborative
|
||||
- Be open-minded
|
||||
|
||||
## How to Contribute
|
||||
|
||||
### Reporting Bugs
|
||||
|
||||
If you find a bug, please report it by creating an issue on GitHub:
|
||||
|
||||
1. Go to the [Issues](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues) page
|
||||
2. Click "New Issue"
|
||||
3. Select "Bug Report"
|
||||
4. Fill out the template with as much detail as possible
|
||||
5. Submit the issue
|
||||
|
||||
Please include:
|
||||
|
||||
- A clear, descriptive title
|
||||
- Steps to reproduce the bug
|
||||
- Expected behavior
|
||||
- Actual behavior
|
||||
- Screenshots (if applicable)
|
||||
- Your environment (WordPress version, PHP version, browser, etc.)
|
||||
|
||||
### Suggesting Enhancements
|
||||
|
||||
If you have an idea for an enhancement:
|
||||
|
||||
1. Go to the [Issues](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues) page
|
||||
2. Click "New Issue"
|
||||
3. Select "Feature Request"
|
||||
4. Fill out the template with as much detail as possible
|
||||
5. Submit the issue
|
||||
|
||||
Please include:
|
||||
|
||||
- A clear, descriptive title
|
||||
- A detailed description of the enhancement
|
||||
- Why this enhancement would be useful
|
||||
- Any relevant examples or mockups
|
||||
|
||||
### Pull Requests
|
||||
|
||||
If you want to contribute code:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a new branch for your feature or bugfix
|
||||
3. Make your changes
|
||||
4. Run tests to ensure your changes don't break anything
|
||||
5. Submit a pull request
|
||||
|
||||
#### Pull Request Process
|
||||
|
||||
1. Fork the repository on [GitHub](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/) or [Gitea](https://gitea.wpallstars.com/wpallstars/wp-plugin-starter-template-for-ai-coding/)
|
||||
2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/wp-plugin-starter-template-for-ai-coding.git`
|
||||
3. Create your feature branch: `git checkout -b feature/amazing-feature`
|
||||
4. Make your changes
|
||||
5. Commit your changes: `git commit -m 'Add some amazing feature'`
|
||||
6. Push to the branch: `git push origin feature/amazing-feature`
|
||||
7. Submit a pull request
|
||||
|
||||
#### Pull Request Guidelines
|
||||
|
||||
- Follow the coding standards (see [Coding Standards](Coding-Standards))
|
||||
- Write tests for your changes
|
||||
- Update documentation as needed
|
||||
- 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
|
||||
|
||||
To set up your development environment:
|
||||
|
||||
1. Clone the repository: `git clone https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding.git`
|
||||
2. Install dependencies: `composer install && npm install`
|
||||
3. Start the development environment: `npm run start`
|
||||
|
||||
### Testing
|
||||
|
||||
Before submitting a pull request, make sure to run the tests:
|
||||
|
||||
- PHP Unit Tests: `npm run test:php`
|
||||
- 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:
|
||||
|
||||
- Update the README.md file if necessary
|
||||
- Update the readme.txt file if necessary
|
||||
- Update or create wiki pages as needed
|
||||
- Update code comments
|
||||
|
||||
## Community
|
||||
|
||||
Join our community to discuss the project:
|
||||
|
||||
- [GitHub Discussions](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding/discussions)
|
||||
- [Gitea Issues](https://gitea.wpallstars.com/wpallstars/wp-plugin-starter-template-for-ai-coding/issues)
|
||||
|
||||
## Recognition
|
||||
|
||||
Contributors will be recognized in the following ways:
|
||||
|
||||
- Added to the contributors list in readme.txt
|
||||
- Mentioned in release notes for significant contributions
|
||||
- Thanked in the Changelog for specific contributions
|
||||
|
||||
## License
|
||||
|
||||
By contributing to this project, you agree that your contributions will be licensed under the project's [GPL-2.0+ License](https://www.gnu.org/licenses/gpl-2.0.html).
|
||||
|
||||
## Questions?
|
||||
|
||||
If you have any questions about contributing, please open an issue or contact the maintainers.
|
||||
|
||||
Thank you for your contributions!
|
||||
Reference in New Issue
Block a user