wp-cli/.github

🌐 Centralized community health files for all repositories

Quick links: Using | Installing | Contributing | Support

This package cannot be used directly. It is a container to provide centralized fallback for community health files for the wp-cli Github organization.

See: https://help.github.com/en/articles/creating-a-default-community-health-file-for-your-organization

This repository contains reusable GitHub Actions workflows that are automatically synced to all WP-CLI repositories:

• Code Quality Checks (code-quality.yml) - Runs linting, PHPCS, PHPStan, and other code quality tools
• Regenerate README (regenerate-readme.yml) - Automatically regenerates README.md files from source
• Check Branch Alias (check-branch-alias.yml) - Monitors and updates Composer branch-alias configuration

A package's testing.yml can call the test workflows in one of two shapes.

The wrapped shape is the default and needs three lines:

jobs:
  test:
    uses: wp-cli/.github/.github/workflows/reusable-testing.yml@main
    with:
      minimum-php: '8.0'

The fanned-out shape calls reusable-prepare-matrix.yml for the matrix and runs the legs from the package's own jobs. See this repository's own testing.yml for a complete example.

The only thing it buys is presentation: a matrix becomes a collapsible group in the Actions run view only when it sits on a job declared in the workflow the run belongs to. In the wrapped shape the matrix is one level down and is not surfaced, so all fifty legs appear as one flat list. Fanning out puts the matrix at the top level, so the run view collapses to one entry per PHP version.

It costs about thirty lines in a file that is not synced, so every future change to the fan-out has to be repeated in each package that adopts it. Prefer the wrapped shape unless a package has a large enough matrix that the flat list is genuinely hard to read.

A fanned-out caller should pass grouped: true to reusable-unit.yml and reusable-functional.yml, so their job names leave out what the group header already states. Without it the legs read Behat | PHP 8.5 | WP latest | SQLite inside a group already called Behat | PHP 8.5.

The run view groups legs whose calling job name is identical, so that name must vary by the dimension being grouped on and collide across every other one. Group both suites by PHP version:

Behat | PHP 8.5                    <- the calling job
  WP latest | mysql-8.0            <- the called workflow, with grouped: true
  WP trunk  | SQLite

Unit | PHP 8.5
  PHPUnit (with coverage)
  PHPUnit (macOS)
  PHPUnit (Windows)

A name that does not vary with the matrix does not collapse the legs into one group. GitHub appends the matrix combination to disambiguate it, so name: Unit produces one group per leg, labelled Unit (8.5, latest, mysql-8.0).

Some groups will hold a single leg — on a pull request there is one unit leg per PHP version, because the macOS and Windows entries only run on the nightly schedule. That is expected and still reads better than the alternative.

Wrapped callers must leave grouped at its default of false, because there is no group header for them and the name has to stand on its own.

The one thing to watch is that with grouped: true a leg name is only unique within its group — WP latest | SQLite occurs under every PHP version. That is fine wherever the group header is part of the name, which is how the run view and the checks list both render it. If a leg ever shows up somewhere without its group, set grouped: false for that caller and the full name comes back.

The branch alias checker workflow automatically ensures that the Composer branch-alias in each repository's composer.json is up-to-date. It:

1. Runs on every release or can be triggered manually
2. Checks the latest release tag
3. On a new major release (vX.0.0), updates the branch-alias to X.x-dev
4. Skips minor and patch releases, as the branch-alias should remain unchanged
5. Creates a pull request if an update is needed

For example, if a repository releases v2.2.6 or v2.3.0, the branch-alias stays at 2.x-dev. Only when releasing v3.0.0 should it change to 3.x-dev.

There's nothing to install, this package cannot be used directly.

We appreciate you taking the initiative to contribute to this project.

Contributing isn’t limited to just code. We encourage you to contribute in the way that best fits your abilities, by writing tutorials, giving a demo at your local meetup, helping other users with their support questions, or revising our documentation.

For a more thorough introduction, check out WP-CLI's guide to contributing. This package follows those policy and guidelines.

Think you’ve found a bug? We’d love for you to help us get it fixed.

Before you create a new issue, you should search existing issues to see if there’s an existing resolution to it, or if it’s already been fixed in a newer version.

Once you’ve done a bit of searching and discovered there isn’t an open or fixed issue for your bug, please create a new issue. Include as much detail as you can, and clear steps to reproduce if possible. For more guidance, review our bug report documentation.

Want to contribute a new feature? Please first open a new issue to discuss whether the feature is a good fit for the project.

Once you've decided to commit the time to seeing your pull request through, please follow our guidelines for creating a pull request to make sure it's a pleasant experience. See "Setting up" for details specific to working on this package locally.

Github issues aren't for general support questions, but there are other venues you can try: https://wp-cli.org/#support