There are many ways to contribute to this project.

• Discuss open issues to help define the future of the project.
• Submit bugs and help us verify fixes as they are checked in.
• Review and discuss the source code changes.
• Contribute bug fixes

• /packages - NPM packages
• /examples - Example projects
• /plugins - WordPress Plugins
• /scripts - Packaging scripts

NPM packages are managed from the project root using Workspaces. To get started, run:

1. npm install
2. npm run dev

The local copy of each package is automatically symlinked in node_modules when running npm install from the project root. Likewise, each package is automatically built when running npm run dev.

When switching git branch, run npm run clean from the root and then re-run npm run dev.

As this is a monorepo, you will not be able to check out this repository into wp-content/themes or wp-content/plugins.

Instead, you can create symlinks to the themes/plugins in this repository. Best of all, this will also sync your work across multiple local sites!

Setup To begin working with the FaustWP WordPress plugin, you will need to symlink the plugin from the monorepo to your WordPress plugin development directory.

ln -s /path/to/faustjs/plugins/faustwp /path/to/wordpress/wp-content/plugins/faustwp

PHP Code Sniffer PHP Code Sniffer is configured for the WordPress code standards.

Install the composer packages from within plugins/faustwp directory if you haven't already.

composer install

Run the syntax check.

composer phpcs

Use phpcs to fix some syntax errors:

composer phpcs:fix

WordPress Unit Tests

To run WordPress unit tests, first start the Docker application from the plugins/faustwp directory:

composer run docker:start

If desired, you may specify the WP_VERSION you'd like to run tests against:

WP_VERSION=6.4.2 composer run docker:start

Once the containers are up, set up the test framework. If you want to enable code coverage reporting, make sure you provide the COVERAGE=1 environment variable as a parameter:

docker-compose exec -e COVERAGE=1 wordpress init-testing-environment.sh

Install and activate WP GraphQL:

docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) wp plugin install wp-graphql --activate --allow-root

Run the unit tests:

docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) composer test

Finally, to remove the containers:

composer run docker:stop

Use Codeception for running end-2-end tests in the browser.

1. Install Docker.
2. Install Composer.
3. Install Google Chrome.
4. Install Chromedriver
   • The major version will need to match your Google Chrome version. See Chromedriver Version Selection.
   • Unzip the chromedriver zip file and move chromedriver application into the /usr/local/bin directory. mv chromedriver /usr/local/bin
   • In shell, run chromedriver --version. Note: If you are using OS X, it may prevent this program from opening. Open "Security & Privacy" and allow chromedriver.
   • Run chromedriver --version again. Note: On OS X, you may be prompted for a final time, click "Open". When you can see the version, chromedriver is ready.

1. Create the following .env.test in examples/next/faustwp-getting-started.

# Your WordPress site URL
NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8080

# Plugin secret found in WordPress Settings->Headless
FAUST_SECRET_KEY=00000000-0000-4000-8000-000000000001

2. From within examples/next/faustwp-getting-started, run NODE_ENV=test npm run dev.

1. Leave the node server running and open a new shell.
2. Move into the FaustWP plugin directory plugins/faustwp.
3. Run composer install if you haven't already.
4. Prepare a test WordPress site.
   1. Run docker-compose up -d --build. If building for the first time, it could take some time to download and build the images.
   2. Run docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) wp plugin install wp-graphql --activate --allow-root
   3. Run docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) wp core update-db --allow-root
   4. Run docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) wp db export tests/_data/dump.sql --allow-root
5. Copy .env.testing.example to .env.testing.
6. Run vendor/bin/codecept run acceptance to start the end-2-end tests.

• Codeception Acceptance Tests
  • Base framework for browser testing in php.
• WPBrowser
  • WordPress framework wrapping Codeception for browser testing WordPress.

We have two notable branches:

• canary - This branch has the latest changes. faustjs.org reads the docs folder from this branch, so merged docs changes go live within about 10 minutes.
• main - This branch is frozen. Don't delete it; external tools still link to examples on it.

We use the feature branch workflow. The workflow for a typical code change looks like:

• Create a new branch for the feature
• Make changes to the code
• Commit your changes
• Open a pull request to the canary branch with a Conventional Commits title, scoped to the package you changed (e.g. fix(core): ..., feat(faustwp): ...)
• Squash and Merge the pull request into the canary branch

Note: We use Squash and Merge when merging pull requests into the canary branch, so the pull request title becomes the commit message that drives versioning and changelogs.

Developers with full GitHub repository access can create public releases. We use release-please to automate versioning and deployment for all of our packages and the plugin. Configuration lives in release-please-config.json and .release-please-manifest.json.

release-please reads the commits merged to canary since the last release of each package. Only commits that touch a package's directory count toward that package.

• fix: releases a patch version.
• feat: releases a minor version.
• ! after the type (e.g. feat!:) or a BREAKING CHANGE: footer releases a major version.
• deps: releases a patch version and lists the change under Dependencies.
• chore:, docs:, ci:, test:, refactor:, build:, and style: don't trigger a release.

@faustwp/core and @faustwp/cli always share a version number.

release-please keeps a release PR open against canary and updates it as commits land.

1. Go to pull requests, and view the release-please PR.
2. Review the PR:
   • Changelog entries were created in all updated packages or plugins.
   • Version numbers were appropriately bumped in the relevant package.json files.
   • Version number updated in the main plugin file and readme.txt (Plugin versioning only)
   • The plugin's readme.txt changelog has been updated with the latest 3 versions (Plugin versioning only)
3. Approve, then "Squash and merge" the release PR into canary.

Merging the release PR tags each released package (e.g. @faustwp/core@3.4.2), creates a GitHub release for it, and publishes the npm packages. If the plugin was released, the same workflow deploys it to WordPress.org.

Once deployed, the updated packages and plugin will be visible here:

• https://www.npmjs.com/package/@faustwp/core
• https://www.npmjs.com/package/@faustwp/cli
• https://www.npmjs.com/package/@faustwp/blocks
• https://plugins.trac.wordpress.org/browser/faustwp/tags

This section offers guidance for developers working within the monorepo environment, which utilizes npm for package management.

• Use your terminal or IDE to navigate the file structure.
• To locate a specific project, navigate to its directory within the packages folder. For example, cd packages/faustwp-core would take you to the faustwp-core project directory.

• We use npm for managing dependencies and running build scripts.
• Individual projects often have their own package.json file with project-specific scripts for building and deploying. You can run these scripts using commands like npm run build or npm run test within the project directory (e.g., packages/faustwp-core).
• Refer to the project's README file or internal documentation for specific build and deploy instructions. For deploying the entire monorepo, there might be a top-level build script which you can invoke with npm run build.

Use the --workspaces or -w flag to run a specific script command of a specified workspace. For example:

$ npm run build -w examples/next/faustwp-getting-started

It runs the build npm script for the faustwp-getting-started example project.