Skip to content

Latest commit

 

History

History
94 lines (63 loc) · 4.59 KB

CONTRIBUTING.md

File metadata and controls

94 lines (63 loc) · 4.59 KB

Contributing to the WordPress AI Client package

Thank you for your interest in contributing to the WordPress AI Client package! Here you find some information on how to get started. As this repository is in its very early stages, expect more detailed instructions to come soon.

Coding standards

All code in this project must follow the WordPress Coding Standards. Since it is a Composer package, there are a few exceptions to this, most importantly the file names which should match the respective class, to facilitate PSR-4 autoloading. But other than that the code must adhere to the WordPress Coding Standards.

All parameters, return values, and properties must use explicit type hints, except in cases where providing the correct type hint would be impossible given limitations of the oldest supported PHP version (see below).

Naming conventions

The following naming conventions must be followed for consistency and autoloading:

  • Interfaces are suffixed with _Interface.
  • Traits are suffixed with _Trait.
  • Enums are suffixed with _Enum.
  • File names are the same as the class, trait, and interface name for PSR-4 autoloading.
  • Classes, interfaces, and traits, and namespaces are not prefixed with AI_, excluding the root namespace.

Documentation standards

All code must be properly documented with PHPDoc blocks following these standards:

General rules

  • All descriptions must end with a period.
  • Use @since n.e.x.t for new code (will be replaced with actual version on release).
  • Place @since tags below the description and above @param tags, with blank comment lines around it.

Method documentation

  • Method descriptions must start with a third-person verb (e.g., "Creates", "Returns", "Checks").
  • Exceptions: Constructors and magic methods may use different phrasing.
  • All @return annotations must include a description.

Interface implementations

  • Use {@inheritDoc} instead of duplicating descriptions when implementing interface methods.
  • Only provide a unique description if it adds value beyond the interface documentation.

Example

/**
 * Class for handling user authentication requests.
 *
 * @since n.e.x.t
 */
class Auth_Handler {

    /**
     * Validates user credentials against the database.
     *
     * @since n.e.x.t
     * 
     * @param string $username The username to validate.
     * @param string $password The password to validate.
     * @return bool True if credentials are valid, false otherwise.
     */
    public function validate( string $username, string $password ): bool {
        // Implementation
    }
}

Array Lists

When an array is a list — that is, an array where the keys are sequential, starting at 0 — use the list generic type within the docblock. For example, a parameter that is a list of strings would be documented as @param list<string> $variable.

Note that list<string> and string[] are not the same. The latter is an alias for array<int, string> which does not enforce that the keys are sequential. That particular syntax, therefore, will rarely be used.

PHP Compatibility

All code must be backward compatible with PHP 7.4, which is the minimum required PHP version for this project.

Branch naming conventions

There are a few protected branch naming conventions:

  • trunk: The main development branch.
  • release/*: A branch for a specific release, useful e.g. for applying a hotfix.
  • feature/*: A branch for a larger feature that takes multiple iterative PRs towards completion.

These special branches are protected and are configured more strictly in regards to GitHub workflow configuration.

Branches that you use for implementing a pull request or experimenting can use any naming convention you prefer, except the above. Additionally, please do not use branch names that would easily cause confusion, such as other common main branch names like main or develop.

Ideally, the branch name is in some form or shape descriptive of what it is for.

Guidelines

  • As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our Code of Conduct.
  • All WordPress projects are licensed under the GPLv2+, and all contributions to the WordPress AI Client package will be released under the GPLv2+ license. You maintain copyright over any contribution you make, and by submitting a pull request, you are agreeing to release that contribution under the GPLv2+ license.