Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
244 lines (179 loc) · 8.02 KB

CONTRIBUTING.md

File metadata and controls

244 lines (179 loc) · 8.02 KB

Contributing to Optimizations ACE MC

Thank you for considering a contribution to Optimizations ACE MC. This guide keeps development, code quality, and review expectations aligned with this plugin.

Code of Conduct

This project follows the WordPress Community Code of Conduct. By participating, you are expected to uphold this code.

Development Environment

Requirements

  • PHP: 8.2 or higher
  • WordPress: 6.8 or higher
  • WooCommerce: Required for WooCommerce-specific optimization behavior
  • WP Store Locator: Required for store locator optimization behavior
  • Composer: For dependency management and quality tools
  • Git: For version control

Setup

  1. Fork the repository on GitHub.

  2. Clone your fork locally:

    git clone https://github.com/YOUR-USERNAME/optimizations-ace-mc.git
cd optimizations-ace-mc

  3. Install dependencies:

    composer install

  4. Create a feature branch:

    git checkout -b feature/your-feature-name

Coding Standards

This project follows WordPress Coding Standards for PHP, JavaScript, CSS, HTML, and accessibility.

Project-owned JavaScript should use modern ES2025+ syntax for the WordPress 6.5+ browser support baseline. Prefer native DOM APIs, const/let, arrow functions, optional chaining, nullish coalescing, template literals, and modules where appropriate. Use legacy JavaScript patterns only when a WordPress or WP Store Locator integration requires them.

Key Principles

  1. Security First: Validate and sanitize input, escape output, protect forms with nonces, and check capabilities before privileged actions.
  2. Performance: Use WordPress caching mechanisms, avoid unnecessary database work, and enqueue assets only where needed.
  3. Internationalization: Mark user-facing strings with WordPress i18n functions and use the optimizations-ace-mc text domain.
  4. Accessibility: Use semantic markup and preserve keyboard and screen reader behavior in admin UI changes.

Code Quality Tools

Run the main checks before submitting a pull request:

composer run phpcs
composer run phpstan
composer run phpmd
composer run psalm
composer test

File Structure

optimizations-ace-mc/
|-- optimizations-ace-mc.php            # Main plugin file
|-- includes/                           # Plugin PHP classes
|   |-- class-optimizations-ace-mc.php
|   |-- class-optimizations-ace-mc-admin-page.php
|   |-- class-optimizations-ace-mc-settings.php
|   |-- class-optimizations-ace-mc-admin-optimizations.php
|   |-- class-optimizations-ace-mc-woocommerce-optimizations.php
|   `-- class-optimizations-ace-mc-wpsl-optimizations.php
|-- assets/                             # Admin CSS
|-- languages/                          # Translation template
|   `-- optimizations-ace-mc.pot
|-- tests/                              # PHPUnit tests
|-- stubs/                              # Static-analysis stubs
|-- README.md                           # Project documentation
|-- readme.txt                          # WordPress.org readme
|-- CHANGELOG.md                        # Version history
|-- CONTRIBUTING.md                     # This file
|-- LICENSE                             # GPL license
|-- composer.json                       # PHP dependencies
|-- phpcs.xml                           # PHPCS configuration
|-- phpstan.neon                        # PHPStan configuration
|-- phpmd.xml                           # PHPMD configuration
`-- .github/                            # GitHub workflows and templates

Making Changes

Before You Start

  1. Check existing issues and pull requests.
  2. Create an issue for significant behavior changes.
  3. Follow the existing code patterns in the relevant includes/ class.

Code Requirements

  • Input validation: Validate all user input before use.
  • Output escaping: Use esc_html(), esc_attr(), esc_url(), or another context-appropriate escaping function.
  • Sanitization: Use WordPress sanitizers such as sanitize_text_field(), sanitize_textarea_field(), and absint().
  • Nonce verification: Use WordPress nonces for forms and state-changing requests.
  • Capability checks: Verify permissions with current_user_can().
  • PHPDoc: Add @param, @return, and @since tags for new public functions and methods.

Example Function

/**
 * Example function with proper documentation.
 *
 * @since 1.0.9
 * @param string $input User input to process.
 * @return string Sanitized output.
 */
function optimizations_ace_mc_example_function( string $input ): string {
    if ( ! current_user_can( 'manage_options' ) ) {
        return '';
    }

    $sanitized = sanitize_text_field( $input );

    return esc_html( $sanitized );
}

Testing

  1. Manual testing:

    • Test with WordPress 6.8 or higher.
    • Test with PHP 8.2 or higher.
    • Verify the settings screen at Settings > Optimizations ACE MC.
    • Verify WooCommerce user order count behavior when enabled.
    • Verify WP Store Locator category display and REST API behavior when enabled.
    • Verify the WordPress user registration date column when enabled.

  2. Automated testing:

    • Run PHPCS for coding standards.
    • Run PHPStan and Psalm for static analysis.
    • Run PHPMD for code quality checks.
    • Run PHPUnit tests.

Submitting Changes

Pull Request Process

  1. Create a feature branch:

    git checkout -b feature/description-of-change

  2. Make your changes:

    • Follow WordPress coding standards.
    • Add or update tests where useful.
    • Update documentation when behavior changes.

  3. Run checks:

    composer run check-all

  4. Commit your changes:

    git add .
git commit -m "fix: update optimization behavior"

  5. Push and open a pull request:

    git push origin feature/description-of-change

Commit Message Format

Use Conventional Commits:

  • feat: New features
  • fix: Bug fixes
  • docs: Documentation changes
  • style: Code style changes
  • refactor: Code refactoring
  • test: Test additions or changes
  • chore: Maintenance tasks

Pull Request Checklist

  • Code follows WordPress coding standards
  • Public functions and methods have useful PHPDoc
  • Security best practices are implemented
  • PHPCS, PHPStan, PHPMD, Psalm, and PHPUnit checks pass
  • Manual testing is complete
  • Documentation is updated if needed
  • CHANGELOG.md and readme.txt are updated if behavior changes

Version Management

When releasing new versions, update these files:

  • optimizations-ace-mc.php plugin header
  • includes/ version-dependent UI copy if needed
  • README.md
  • readme.txt
  • CHANGELOG.md
  • languages/optimizations-ace-mc.pot

This project follows Semantic Versioning:

  • MAJOR: Breaking changes
  • MINOR: New features
  • PATCH: Bug fixes

Support Channels

Resources

License

By contributing to Optimizations ACE MC, you agree that your contributions will be licensed under GPL-3.0-or-later.