Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
87b1d16
Prepare Foundation 2.0 container, logging, shutdown and view packages
defunctl Oct 30, 2026
37a23af
Allow SLIC coverage reporting to publish PR status and comments
defunctl Oct 30, 2026
73429eb
Document config-file bootstrap and shared configuration migration
defunctl Oct 30, 2026
3a75654
Restore package introductions and remove redundant PHP requirements
defunctl Oct 30, 2026
74032d0
Align package README installation and introduction format
defunctl Oct 30, 2026
58e4393
Restore complete Container setup and configuration examples
defunctl Oct 30, 2026
9d7962b
Focus Container README on setup and usage examples
defunctl Oct 30, 2026
40dbf5f
Follow the original Container README structure and example flow
defunctl Oct 30, 2026
8b0b046
Highlight provider registration order with a GitHub alert
defunctl Oct 30, 2026
4beb651
Restore service provider heading and optional environment example
defunctl Oct 30, 2026
835130a
Restore Container capabilities introduction
defunctl Oct 30, 2026
0660f06
Add configuration assembly tip to Container README
defunctl Oct 30, 2026
45ac125
Declare read-only CI defaults and clarify stack logging destinations
defunctl Oct 30, 2026
3c41160
Restore package creation guidance after workflow removal
defunctl Oct 30, 2026
78cad36
Fix deferred resolver factories and custom logging thresholds
defunctl Oct 30, 2026
86e9dff
Run Foundation workflows on Blacksmith with explicit Composer setup
defunctl Oct 30, 2026
46444c5
Include Pipeline execution contract and lifecycle fixes from PR 6
defunctl Oct 30, 2026
9dca5d2
Preserve handler thresholds and verify split publication
defunctl Oct 31, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .github/workflows/check-for-required-files.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,12 @@ on:
branches:
- main

permissions:
contents: read

jobs:
check-workflows:
runs-on: ubuntu-latest
runs-on: blacksmith-2vcpu-ubuntu-2404

steps:
- name: Check out repository
Expand All @@ -20,7 +23,6 @@ jobs:
# Find all subdirectories in src/ and look for required files
for folder in */; do
file_paths=(
"$folder.github/workflows/close-pull-request.yml"
"$folder/.gitattributes"
"$folder/.gitignore"
)
Expand Down
41 changes: 37 additions & 4 deletions .github/workflows/monorepo-split.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,20 @@ on:
tags:
- '*'

permissions:
contents: read

# The action updates the same split branches for main and tags; serialize publication.
concurrency:
group: foundation-package-publication
cancel-in-progress: false

env:
GITHUB_TOKEN: ${{ secrets.GH_BOT_TOKEN }}

jobs:
list-repos:
runs-on: ubuntu-latest
runs-on: blacksmith-2vcpu-ubuntu-2404
outputs:
matrix: ${{ steps.set-matrix.outputs.matrix }}

Expand All @@ -28,7 +36,7 @@ jobs:

split:
needs: list-repos
runs-on: ubuntu-latest
runs-on: blacksmith-2vcpu-ubuntu-2404

strategy:
fail-fast: false
Expand All @@ -39,6 +47,9 @@ jobs:
- name: Checkout
uses: actions/checkout@v6

- name: Check split credentials
run: test -n "$GITHUB_TOKEN"

# no tag
- name: Split with no tag
if: ${{ ! startsWith(github.ref, 'refs/tags/') }}
Expand All @@ -57,7 +68,7 @@ jobs:
if: ${{ startsWith(github.ref, 'refs/tags/')}}
uses: moderntribe/monorepo-split-github-action@4.0.2
with:
tag: "${GITHUB_REF#refs/tags/}"
tag: ${{ github.ref_name }}

package_directory: 'src/${{ matrix.package.directory }}'
repository_organization: 'stellarwp'
Expand All @@ -67,10 +78,31 @@ jobs:
user_name: "StellarWP GitHub Action"
user_email: "action@github.com"

# The upstream split action does not consistently fail on unsuccessful git pushes.
- name: Verify published package tree
env:
GH_TOKEN: ${{ secrets.GH_BOT_TOKEN }}
PACKAGE_REPOSITORY: ${{ matrix.package.name }}
PACKAGE_DIRECTORY: ${{ matrix.package.directory }}
shell: bash
run: |
set -euo pipefail
published_ref=main
if [[ "$GITHUB_REF" == refs/tags/* ]]; then
published_ref="$GITHUB_REF_NAME"
fi
expected_tree=$(git rev-parse "${GITHUB_SHA}:src/${PACKAGE_DIRECTORY}")
actual_tree=$(gh api "repos/stellarwp/${PACKAGE_REPOSITORY}/commits/${published_ref}" --jq '.commit.tree.sha')
if [[ "$actual_tree" != "$expected_tree" ]]; then
echo "Published ${PACKAGE_REPOSITORY}@${published_ref} does not match the release source."
exit 1
fi
echo "Verified ${PACKAGE_REPOSITORY}@${published_ref}."

bump-next-development-line:
needs: split
if: ${{ startsWith(github.ref, 'refs/tags/') }}
runs-on: ubuntu-latest
runs-on: blacksmith-2vcpu-ubuntu-2404

steps:
- name: Determine next development line
Expand Down Expand Up @@ -107,6 +139,7 @@ jobs:
with:
php-version: '8.3'
coverage: none
tools: composer:v2

- name: Install Composer dependencies
if: ${{ steps.version.outputs.should_bump == 'true' }}
Expand Down
7 changes: 6 additions & 1 deletion .github/workflows/quality.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,13 @@ on:
branches:
- main

permissions:
contents: read
pull-requests: read

jobs:
ci:
runs-on: ubuntu-latest
runs-on: blacksmith-2vcpu-ubuntu-2404
name: Code Quality

steps:
Expand All @@ -19,6 +23,7 @@ jobs:
with:
php-version: '8.3'
coverage: pcov
tools: composer:v2

- name: Detect File Changes
uses: dorny/paths-filter@v4
Expand Down
101 changes: 94 additions & 7 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,18 @@ on:
branches:
- main

permissions:
contents: read

jobs:
ci:
runs-on: ${{ matrix.os }}
runs-on: blacksmith-2vcpu-ubuntu-2404
strategy:
fail-fast: true
matrix:
os: [ ubuntu-latest ]
php: [ '8.3', '8.4', '8.5' ]
name: Tests PHP${{ matrix.php }} - ${{ matrix.os }}
# Preserve existing required-check names when changing runner providers.
name: Tests PHP${{ matrix.php }} - ubuntu-latest

steps:
- name: Checkout code
Expand All @@ -24,6 +27,7 @@ jobs:
with:
php-version: ${{ matrix.php }}
coverage: none
tools: composer:v2

- name: Install Composer dependencies
uses: ramsey/composer-install@v4
Expand All @@ -36,8 +40,43 @@ jobs:
- name: Run Feature Tests
run: vendor/bin/phpunit --configuration ./phpunit.xml.dist --colors=always --testsuite Feature

monolog:
runs-on: blacksmith-2vcpu-ubuntu-2404
name: Monolog ${{ matrix.monolog }} compatibility
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
strategy:
fail-fast: false
matrix:
monolog: [ '2.11.0', '3.10.0' ]

steps:
- name: Checkout code
uses: actions/checkout@v6

- name: Set up PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.3'
coverage: none
tools: composer:v2

- name: Install Composer dependencies
uses: ramsey/composer-install@v4
with:
dependency-versions: highest

- name: Install supported Monolog floor
run: composer update monolog/monolog:${{ matrix.monolog }} --with-all-dependencies --no-interaction --prefer-dist

- name: Analyze supported Monolog APIs
run: composer analyze

- name: Test logging behavior
run: |
vendor/bin/phpunit --configuration phpunit.xml.dist tests/Unit/Log
vendor/bin/phpunit --configuration phpunit.xml.dist tests/Feature/Log

slic:
runs-on: ubuntu-latest
runs-on: blacksmith-2vcpu-ubuntu-2404
name: SLIC Tests

env:
Expand All @@ -55,6 +94,27 @@ jobs:
path: slic
fetch-depth: 1

- name: Set up host PHP and Composer
uses: shivammathur/setup-php@v2
with:
php-version: '8.3'
coverage: none
tools: composer:v2

- name: Get Composer cache directory
id: composer-cache-directory
run: |
cache_directory=$(composer config cache-dir --absolute)
echo "path=$cache_directory" >> "$GITHUB_OUTPUT"

- name: Restore Composer cache
uses: actions/cache@v6
with:
path: ${{ steps.composer-cache-directory.outputs.path }}
key: ${{ runner.os }}-composer-slic-php8.3-v1-${{ hashFiles('composer.lock', 'composer.json', 'src/*/composer.json') }}
restore-keys: |
${{ runner.os }}-composer-slic-php8.3-v1-

- name: Set SLIC environment variables
run: |
echo "SLIC_BIN=${GITHUB_WORKSPACE}/slic/slic" >> $GITHUB_ENV
Expand All @@ -70,6 +130,8 @@ jobs:
echo "SSH_AUTH_SOCK=/tmp/ssh_agent.sock" >> $GITHUB_ENV

- name: Configure SLIC
env:
COMPOSER_CACHE_PATH: ${{ steps.composer-cache-directory.outputs.path }}
run: |
cd "${GITHUB_WORKSPACE}/.."
"${SLIC_BIN}" here
Expand All @@ -79,13 +141,13 @@ jobs:
"${SLIC_BIN}" xdebug off
"${SLIC_BIN}" debug on
"${SLIC_BIN}" php-version set 8.3 --skip-rebuild
"${SLIC_BIN}" composer-cache set "$COMPOSER_CACHE_PATH"
"${SLIC_BIN}" info
"${SLIC_BIN}" config

- name: Install dependencies
run: |
"${SLIC_BIN}" use foundation
"${SLIC_BIN}" composer set-version 2
"${SLIC_BIN}" composer install

- name: Update WordPress
Expand Down Expand Up @@ -121,14 +183,39 @@ jobs:
run: |
"${SLIC_BIN}" run --coverage --coverage-xml clover.xml --disable-coverage-php --ext DotReporter

- name: Monitor coverage
- name: Upload coverage report
if: github.event_name == 'pull_request'
uses: actions/upload-artifact@v7
with:
name: coverage-report
path: tests/_output/clover.xml
if-no-files-found: error
retention-days: 1

coverage:
if: github.event_name == 'pull_request'
needs: slic
runs-on: blacksmith-2vcpu-ubuntu-2404
name: Monitor coverage

permissions:
contents: read
pull-requests: write
statuses: write

steps:
- name: Download coverage report
uses: actions/download-artifact@v8
with:
name: coverage-report

- name: Monitor coverage
uses: slavcodev/coverage-monitor-action@v1
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
comment_footer: false
coverage_format: clover
coverage_path: tests/_output/clover.xml
coverage_path: clover.xml
threshold_alert: 90
threshold_warning: 95
threshold_metric: "lines"
12 changes: 10 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ Initial packages:

- `stellarwp/foundation-container`
- `stellarwp/foundation-log`
- `stellarwp/foundation-shutdown`
- `stellarwp/foundation-view`
- `stellarwp/foundation-pipeline`
- `stellarwp/foundation-wpcli`
- `stellarwp/foundation-cli`
Expand Down Expand Up @@ -73,6 +75,12 @@ When writing providers or container registration code, prefer container-driven c

Use contextual bindings with `$this->container->when()->needs()->give()` for scalar constructor arguments, command lists, or feature-specific substitutions. Use a factory closure only when the value must be computed or resolved from the container, and keep that closure focused on supplying the constructor dependency rather than constructing the full object.

Ordinary providers extend `Provider`, whose final constructor supplies the shared container and configuration snapshot. Applications with their own registration abstraction may implement `Providable`; it requires only `register(): void`. Keep the default examples on `Provider` and document the interface as an integration extension point. Do not restore DI52's deferred provider lifecycle. Register providers once per container in dependency order.

Use Foundation's `Resolver` contract for factory callbacks. Keep raw DI52 access inside the adapter and factory. Bootstrap configuration before registering providers using `ContainerFactory` and `ArrayConfiguration`.

Package READMEs and the root upgrade guide contain the release documentation. This release does not ship the Foundation documentation-site package.

## Split Packages

Split packages live in `src/<Package>/` and are split to read-only repositories named `stellarwp/foundation-<package>`.
Expand All @@ -91,7 +99,6 @@ Each split package should include:
- `README.md`
- `.gitattributes`
- `.gitignore`
- `.github/workflows/close-pull-request.yml`

When adding a new split package, add its `stellarwp/foundation-<package>` repository link to the root `README.md` repositories list.

Expand Down Expand Up @@ -164,7 +171,8 @@ After completing a feature, run `composer test:coverage`, review `clover.xml` fo
- Adding a new split package is usually a minor SemVer release because it introduces new functionality without breaking existing packages. Use a major release only if the change also breaks an existing public API or package contract.
- Run `composer monorepo bump-interdependency <constraint>` when planning a major version release so Foundation packages that depend on each other require the new major line, for example `^3.0`. It may also be useful for a minor release when one package must require APIs added in that new minor, for example `^1.1`.
- Before publishing a release, verify the intended release-line package constraints are already committed. For a minor release such as `1.2.0`, internal Foundation package dependencies should already require the released line, for example `^1.2`.
- Publishing a GitHub release creates the release tag and triggers the tagged monorepo split. Wait for the tagged `Split Monorepo Packages and Release` workflow to succeed before considering the release complete.
- Verify all target split repositories exist and their packages are registered on Packagist before publication. `GH_BOT_TOKEN` must be available to the workflow, have contents and workflow write access to those repositories, and belong to an actor allowed to push the post-release bump to protected `main`. The workflow token cannot supply cross-repository write access.
- Publishing a GitHub release creates the release tag and triggers the tagged monorepo split. Wait for the tagged `Split Monorepo Packages and Release` workflow, including package-tree verification, to succeed. Verify Composer installation of the aggregate and split releases afterward.
- After a successful tagged split for a minor or major `.0` release, the split workflow automatically bumps internal package constraints and branch aliases to the next development line on `main`, for example from `^1.2` and `1.2.x-dev` to `^1.3` and `1.3.x-dev`.
- The post-release automation intentionally skips patch tags such as `1.2.1`, because patch releases should not move `dev-main` to a new minor development line.
- If the post-release automation fails, fetch the release tag and manually run `composer monorepo bump-interdependency <next-dev-constraint>`, `composer monorepo package-alias`, and `composer monorepo merge`, then commit and push the updated package `composer.json` files.
Expand Down
12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,13 @@ Foundation is a StellarWP Composer monorepo for reusable PHP packages intended f
- [stellarwp/foundation-container](https://github.com/stellarwp/foundation-container)
- [stellarwp/foundation-pipeline](https://github.com/stellarwp/foundation-pipeline)
- [stellarwp/foundation-log](https://github.com/stellarwp/foundation-log)
- [stellarwp/foundation-shutdown](https://github.com/stellarwp/foundation-shutdown)
- [stellarwp/foundation-view](https://github.com/stellarwp/foundation-view)
- [stellarwp/foundation-wpcli](https://github.com/stellarwp/foundation-wpcli)
- [stellarwp/foundation-cli](https://github.com/stellarwp/foundation-cli)

See [Upgrading to 2.0](UPGRADING-2.0.md) when moving from Foundation 1.x. Package READMEs contain the setup and API guidance for this release.

## Installation

Install the aggregate package when you want the convenient all-in-one Foundation package:
Expand Down Expand Up @@ -112,9 +116,11 @@ Before drafting the release, run only the monorepo maintenance commands that pre
| You are planning a major version release, for example `2.0` to `3.0`. You should run this so any Foundation packages that depend on each other require the new major line, such as `^3.0`. You may also run it for a minor release if one package must require APIs added in that new minor version. | `composer monorepo bump-interdependency <release-constraint>`, then `composer monorepo merge` | Updates package-to-package dependency constraints for the release being published. Use the release's minimum Composer constraint, such as `^3.0` or `^1.2`. |
| Internal package constraints already match the release line. | No pre-release monorepo maintenance command is needed. | Continue to drafting the release. |

Before publishing, confirm every repository listed above exists with its read-only settings, each package is registered on [Packagist](https://packagist.org/packages/submit), and the release checks pass. The `GH_BOT_TOKEN` organization secret must be available to this repository, with contents and workflow write access to every split repository and permission to push the post-release bump to protected `main` (an allowed bypass actor). Workflow `GITHUB_TOKEN` permissions do not grant access to other repositories.

After any needed command, commit the updated `composer.json` files. Then draft a new release on [GitHub](https://github.com/stellarwp/foundation/releases/new), following [semver](https://semver.org/) closely.

The [monorepo split GitHub workflow](./.github/workflows/monorepo-split.yml) deploys each project's code to its sub-repository on pushes to `main` and when release tags are pushed. Publishing a GitHub release creates the release tag and triggers the tagged split.
The [monorepo split GitHub workflow](./.github/workflows/monorepo-split.yml) deploys each project's code to its sub-repository on pushes to `main` and when release tags are pushed. Publishing a GitHub release creates the release tag and triggers the tagged split. Wait for the tagged workflow to succeed: it verifies that every published package tree matches the tagged source. Then verify Composer can install the released aggregate and split packages.

After a successful tagged split for a minor or major `.0` release, the workflow automatically moves `dev-main` to the next development line. For example, publishing `1.2.0` causes the workflow to bump internal constraints to `^1.3` and branch aliases to `1.3.x-dev`. Patch releases such as `1.2.1` intentionally skip this step.

Expand All @@ -137,7 +143,7 @@ composer run foundation -- package:create <Package>

The package argument can be a new package component such as `WPCli`, an existing package directory, short package name, or Composer package name, for example `Log`, `foundation-log`, or `stellarwp/foundation-log`.

If the package does not exist yet, the command asks whether to create the local scaffold in `src/<Package>` and asks for the Composer package name with a default such as `stellarwp/foundation-wpcli`. The scaffold includes the required `composer.json`, `README.md`, `.gitattributes`, `.gitignore`, and `close-pull-request.yml` files. After scaffolding, the command runs `composer monorepo merge` so the root `composer.json` includes the new package.
If the package does not exist yet, the command asks whether to create the local scaffold in `src/<Package>` and asks for the Composer package name with a default such as `stellarwp/foundation-wpcli`. The scaffold includes the required `composer.json`, `README.md`, `.gitattributes`, and `.gitignore` files. After scaffolding, the command runs `composer monorepo merge` so the root `composer.json` includes the new package.

The command runs as a dry run by default. It validates the required split package files, prints the target repository name and description, and shows the GitHub CLI commands it will run.

Expand All @@ -151,7 +157,7 @@ The command runs as a dry run by default. It validates the required split packag
composer run foundation -- package:create <Package> --apply
```

The command creates the `stellarwp/foundation-<package>` repository with the standard `[READ ONLY]` description and disables issues, wiki, projects, and pull requests. The package's `close-pull-request.yml` workflow is still included as a fallback guard for read-only split repositories.
The command creates the `stellarwp/foundation-<package>` repository with the standard `[READ ONLY]` description and disables issues, wiki, projects, and pull requests.

#### Generating WP-CLI Commands

Expand Down
Loading