Pull Request Standards

Pull Request Standards

To maintain the quality and consistency of our WordPress contributions, all pull requests (PRs) must adhere to the following standards. Our focus is on ensuring that every change is functional, well-documented, and preserves a clean public interface for the users of this repository.

PR Description Requirements

Every PR must provide a clear context for the reviewers and future users. Use the following structure in your PR description:

• Summary: A concise explanation of the change. What does this PR do?
• Type of Change: Specify if it is a Bug Fix, New Feature, Documentation Update, or Refactor.
• Public Interface Impact: Explicitly state if this PR changes any public-facing functions, WordPress hooks (actions/filters), or configuration constants.
• Related Issues: Link to any relevant issues (e.g., Closes #123).

Commit Message Format

We follow the Conventional Commits specification. This helps in generating automated changelogs and understanding the history of the public API.

Format:

<type>(<scope>): <description>

[optional body]

Common Types:

• feat: A new feature for the user (e.g., a new shortcode or block).
• fix: A bug fix for the user.
• docs: Documentation only changes.
• refactor: A code change that neither fixes a bug nor adds a feature.
• chore: Updating build tasks, package manager configs, etc.

Example:

feat(api): add support for custom post type filtering in WP-JSON

Documentation Standards

If your PR introduces a new public-facing feature or modifies an existing one, you must update the corresponding documentation.

Documenting Public Functions & Hooks

Focus on the usage and the interface. Document the inputs, outputs, and their types.

/**
 * Filter the default metadata for the custom WordPress dashboard.
 * 
 * @param array $metadata {
 *     @type string $version The current version of the plugin.
 *     @type bool   $enabled Whether the dashboard is active.
 * }
 * @param int $user_id The ID of the current user.
 * 
 * @return array Modified metadata array.
 */
apply_filters( 'ua_wordpress_dashboard_metadata', $metadata, $user_id );

README Updates

For significant features, include a usage example in the README or the /docs folder. Ensure code blocks are used to demonstrate how a user should interact with your contribution.

### Usage Example: Custom Filter
To modify the dashboard behavior, use the following filter in your `functions.php`:

```php
add_filter( 'ua_wordpress_dashboard_metadata', function( $metadata, $user_id ) {
    $metadata['enabled'] = false;
    return $metadata;
}, 10, 2 );

API Integrity

1. Breaking Changes: If a change breaks the existing public interface (e.g., removing a public method or changing the signature of a widely used filter), it must be clearly flagged in the PR description with the label BREAKING CHANGE.
2. Internal vs. Public: While internal logic (private helper functions) should be clean, documentation efforts should prioritize the Public Interface (Hooks, REST API endpoints, and Global Functions) as these are what users interact with.
3. Type Safety: Ensure that all new public methods have defined return types and parameter types to improve the developer experience for those using this codebase as a dependency.