Contributing

This page provides guidelines for contributing to the MCP Adapter project, including the GitHub workflow, code review process, issue reporting, and community interaction. For testing procedures, see Testing. For code quality requirements, see Code Quality. For initial setup, see Development Environment Setup.

Contribution Overview

The MCP Adapter project welcomes contributions from the WordPress and AI communities. All contributions must follow WordPress coding standards, pass automated quality checks, and undergo peer review before being merged.

Key Contribution Channels:

• GitHub Issues: Bug reports and feature requests
• GitHub Pull Requests: Code contributions
• WordPress Slack: Community discussion in #core-ai channel
• Security Reports: Private disclosure process (see Security section below)

Core Requirements:

• Follow WordPress Coding Standards
• Minimum WordPress version: 6.8+
• Minimum PHP version: 7.4+
• All code licensed under GPLv2+
• Adhere to WordPress Code of Conduct

Sources: CONTRIBUTING.md1-28

GitHub Workflow

Contribution Lifecycle

Sources: CONTRIBUTING.md5-10

Repository Structure

The repository uses standard WordPress plugin structure with additional development tooling:

Directory/File	Purpose
src/	Core plugin PHP source code
tests/Unit/	PHPUnit unit tests
tests/Integration/	WordPress integration tests
tests/Fixtures/	Test doubles and fixtures
.github/workflows/	CI/CD configuration (test.yml)
phpcs.xml.dist	PHPCS coding standards configuration
phpstan.neon.dist	PHPStan static analysis configuration
composer.json	PHP dependencies and scripts
package.json	Node.js dependencies and npm scripts
.wp-env.json	wp-env Docker environment configuration

Sources: CONTRIBUTING.md43-59 docs/guides/testing.md13-17

Creating Issues

Issues should be created for:

• Bug Reports: Unexpected behavior or errors
• Feature Requests: New capabilities or enhancements
• Documentation: Corrections or improvements to docs
• Questions: Clarifications before implementing changes

Issue Template Checklist:

1. Clear, descriptive title
2. Steps to reproduce (for bugs)
3. Expected vs actual behavior
4. Environment details (PHP version, WordPress version, MCP Adapter version)
5. Relevant error messages or logs
6. Screenshots (if applicable)

Sources: CONTRIBUTING.md7

Opening Pull Requests

All code contributions must be submitted via pull requests:

PR Best Practices:

• One logical change per PR (split large changes into multiple PRs)
• Reference related issues using Closes #123 syntax
• Include test coverage for new functionality
• Update documentation if adding features
• Ensure all commits follow WordPress commit message standards

Sources: CONTRIBUTING.md7 docs/guides/testing.md154-167

Code Review Process

Review Workflow

Review Criteria

Maintainers evaluate pull requests based on:

Criterion	Requirements
Code Quality	Follows WordPress coding standards, passes PHPStan level 8
Testing	Includes unit/integration tests, maintains coverage
Documentation	Code comments, PHPDoc blocks, updated user docs
Backward Compatibility	No breaking changes without discussion
Performance	No significant performance regressions
Security	No vulnerabilities, proper sanitization/validation
WordPress Integration	Uses WordPress APIs appropriately
MCP Compliance	Follows Model Context Protocol specification

Sources: CONTRIBUTING.md11-16

Addressing Feedback

When maintainers request changes:

1. Read all comments carefully - Address each point raised
2. Ask for clarification - If requirements are unclear
3. Make requested changes - Update code and tests
4. Respond to comments - Mark resolved or explain decisions
5. Push updates - CI will automatically re-run
6. Request re-review - Use GitHub's "Re-request review" button

Commit Strategy:

• Small PRs: Use git commit --amend and force push to keep history clean
• Large PRs: Add new commits to preserve review context

Sources: CONTRIBUTING.md7

Community Communication

WordPress Slack

The primary community discussion channel is #core-ai on WordPress Slack:

• Joining: Sign up at chat.wordpress.org
• Channel: wordpress.slack.com/#core-ai

When to use Slack:

• Discuss ideas before creating issues
• Ask questions about implementation approaches
• Coordinate work with other contributors
• Share progress on large features
• Get help with development environment issues

Etiquette:

• Search previous messages before asking
• Use threads to keep conversations organized
• Respect community members' time
• Follow WordPress Code of Conduct

Sources: CONTRIBUTING.md9

Communication Channels by Purpose

Purpose	Channel	Response Time
Bug reports	GitHub Issues	1-3 business days
Feature discussion	Slack #core-ai	Immediate to hours
Code review	GitHub PR comments	1-5 business days
Security issues	Private disclosure	24-48 hours
General questions	Slack #core-ai	Immediate to hours
Documentation fixes	GitHub PR	1-3 business days

Sources: CONTRIBUTING.md7-10

Development Workflow

Initial Setup

The complete setup is documented in Development Environment Setup. Quick reference:

WordPress site available at: http://localhost:8888
Admin credentials: admin / password

Sources: CONTRIBUTING.md30-67

Pre-Commit Checks

Before committing code, run local quality checks:

Quality Gates:

• All PHPCS violations must be fixed (run npm run lint:php:fix)
• PHPStan must report zero errors at level 8
• All tests must pass
• Code coverage should not decrease

Sources: CONTRIBUTING.md69-99

Continuous Integration

CI Configuration:

• Test matrix covers PHP 7.4 through 8.4 with WordPress latest and trunk
• All checks must pass before review
• Coverage reports uploaded to Codecov for PHP 8.4 + WordPress latest
• Configuration: .github/workflows/test.yml

Sources: docs/guides/testing.md154-167

Legal Requirements

Licensing

All contributions to MCP Adapter are released under the GNU General Public License v2 or later (GPLv2+):

• You maintain copyright over your contributions
• By submitting a PR, you agree to release your contribution under GPLv2+
• All dependencies must be GPL-compatible
• Commercial plugins can use this library without restriction

License Header: Every new PHP file should include:

Sources: CONTRIBUTING.md24 LICENSE

Code of Conduct

All contributors must follow the WordPress Community Code of Conduct:

• Be welcoming: Encourage participation from all backgrounds
• Be respectful: Disagree constructively
• Be collaborative: Work together toward shared goals
• Be pragmatic: Focus on what's best for the community
• Step down considerately: Communicate if you need to step back

Violations should be reported to WordPress community moderators.

Sources: CONTRIBUTING.md22

Security Issue Reporting

Private Disclosure

Security vulnerabilities should be reported privately, NOT via public GitHub issues:

1. Email: Security team contact (see SECURITY.md - to be added)
2. Expected Response: 24-48 hours acknowledgment
3. Disclosure Timeline: Coordinated disclosure after fix is released

What qualifies as a security issue:

• Authentication bypass
• Authorization bypass (privilege escalation)
• Remote code execution
• SQL injection
• Cross-site scripting (XSS)
• Information disclosure of sensitive data
• Denial of service vulnerabilities

What does NOT require private reporting:

• General bugs without security implications
• Feature requests
• Documentation issues
• Performance problems

Sources: CONTRIBUTING.md26-28

Security Review Process

Sources: CONTRIBUTING.md26-28

Building for Distribution

Before submitting a PR that affects plugin distribution:

This creates a production-ready plugin ZIP file without development dependencies (PHPUnit, PHPCS, PHPStan, etc.).

Important: Always clean development dependencies before building distribution artifacts to minimize file size and avoid including unnecessary code.

Sources: CONTRIBUTING.md101-110

Getting Help

If you encounter issues during the contribution process:

Issue Type	Solution
Environment setup	See Development Environment Setup
Test failures	See Testing and docs/guides/testing.md
Linting errors	Run npm run lint:php:fix for auto-fixes
PHPStan errors	Review PHPStan documentation and Code Quality
General questions	Ask in #core-ai on WordPress Slack
Documentation unclear	Open an issue to request clarification

Sources: CONTRIBUTING.md1-110 docs/guides/testing.md121-151