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: 7.0 or higher
WooCommerce: Required for WooCommerce-specific optimization behavior
WP Store Locator: Optional; only needed for store locator optimization behavior
Composer: For dependency management and quality tools
Node.js: 22.22.2 or higher, for the JavaScript tests only
Git: For version control

Setup

Fork the repository on GitHub.

Clone your fork locally:

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

Install dependencies:
```
composer install
npm install
```

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 7.0+ 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

Security First: Validate and sanitize input, escape output, protect forms with nonces, and check capabilities before privileged actions.
Performance: Use WordPress caching mechanisms, avoid unnecessary database work, and enqueue assets only where needed.
Internationalization: Mark user-facing strings with WordPress i18n functions and use the optimizations-ace-mc text domain.
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
npm test

composer run check-all runs the PHP checks in one go.

Test Layers

Unit tests (tests/unit, run by composer test): PHPUnit tests that run without WordPress. tests/bootstrap.php defines stand-ins for the WordPress, WooCommerce, and WP Store Locator functions the plugin calls.
WordPress integration tests: the compatibility workflow writes this suite into tests/integration on the runner and runs it against real WordPress versions. It is not kept in the repository.
JavaScript tests (tests/js, run by npm test): Node.js test runner tests for the piece the plugin adds to WP Store Locator's info window template. tests/js/render-info-window.php builds the template and the store data with the plugin's own filters; the tests compile the template with Underscore and read the result with jsdom. PHP must be on the PATH.

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/
|   |-- bootstrap.php                   # WordPress stand-ins for the unit tests
|   |-- OamTestCase.php                 # Base class of the unit tests
|   |-- unit/                           # PHPUnit unit tests
|   `-- js/                             # JavaScript tests
|-- stubs/                              # Static-analysis stubs
|-- README.md                           # Project documentation
|-- readme.txt                          # Plugin readme; the only readme in the release package
|-- CHANGELOG.md                        # Version history
|-- CONTRIBUTING.md                     # This file
|-- SECURITY.md                         # Security policy
|-- LICENSE                             # GPL license
|-- composer.json                       # PHP dependencies and check scripts
|-- package.json                        # JavaScript test dependencies
|-- phpcs.xml                           # PHPCS configuration
|-- phpstan.neon                        # PHPStan configuration
|-- phpmd.xml                           # PHPMD configuration
|-- psalm.xml                           # Psalm configuration
|-- phpunit.xml                         # PHPUnit configuration
|-- .distignore                         # Files left out of the release package
`-- .github/                            # GitHub workflows and templates

The release package holds the main plugin file, readme.txt, LICENSE, includes/, assets/, and languages/. When you add a top-level file or directory, add it to .distignore and .gitattributes unless it must ship; .github/scripts/check-plugin-package.py fails when the package lists disagree.

Making Changes

Before You Start

Check existing issues and pull requests.
Create an issue for significant behavior changes.
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

Manual testing:
- Test with WordPress 7.0 or higher.
- Test with PHP 8.2 or higher.
- Verify the settings screen at Settings > ACE MC Optimizations.
- 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.
Automated testing:
- Run PHPCS for coding standards.
- Run PHPStan and Psalm for static analysis.
- Run PHPMD for code quality checks.
- Run the PHPUnit unit tests with composer test.
- Run the JavaScript tests with npm test.
- Run the JavaScript, Markdown and CSS linters with npm run lint:js, npm run lint:md and npm run lint:css.
- The lint job also runs yamllint, actionlint, zizmor, Ruff and mypy on the workflows and the scripts in .github; .github/lint-requirements.txt pins their versions.
- The compatibility workflow on GitHub runs all of these, and the WordPress integration tests, on every push and pull request.

Submitting Changes

Pull Request Process

Create a feature branch:

git checkout -b feature/description-of-change

Make your changes:
- Follow WordPress coding standards.
- Add or update tests where useful.
- Update documentation when behavior changes.
Run checks:
```
composer run check-all
```

Commit your changes:

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

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, PHPUnit, and JavaScript test 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 and the OPTIMIZATIONS_ACE_MC_VERSION constant
includes/ version-dependent UI copy if needed
README.md, including the version badge
readme.txt stable tag and changelog
CHANGELOG.md
languages/optimizations-ace-mc.pot

This project follows Semantic Versioning:

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

Support Channels

Issues: GitHub Issues
Discussions: GitHub Discussions
Security: Report security issues privately through the vulnerability report form; see SECURITY.md

Resources

License

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

Navigation Menu

Repository navigation

CONTRIBUTING.md

CONTRIBUTING.md

Contributing to Optimizations ACE MC

Code of Conduct

Development Environment

Requirements

Setup

Coding Standards

Key Principles

Code Quality Tools

Test Layers

File Structure

Making Changes

Before You Start

Code Requirements

Example Function

Testing

Submitting Changes

Pull Request Process

Commit Message Format

Pull Request Checklist

Version Management

Support Channels

Resources

License

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to Optimizations ACE MC

Code of Conduct

Development Environment

Requirements

Setup

Coding Standards

Key Principles

Code Quality Tools

Test Layers

File Structure

Making Changes

Before You Start

Code Requirements

Example Function

Testing

Submitting Changes

Pull Request Process

Commit Message Format

Pull Request Checklist

Version Management

Support Channels

Resources

License