From 8dc9640204cb38d69b29e87eaf3ac9d81d969f2d Mon Sep 17 00:00:00 2001 From: Theofanis Despoudis <328805+theodesp@users.noreply.github.com> Date: Wed, 20 Mar 2024 12:47:33 +0000 Subject: [PATCH] Docs: Update Development Guide 2024 (#1848) * Docs: Update Development Guide 2024 * Update DEVELOPMENT.md: Removed legacy docs reference. * DEVELOPMENT.md: Added Monorepo section. --- DEVELOPMENT.md | 80 ++++++++++++++++++++++++-------------------------- 1 file changed, 39 insertions(+), 41 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 915f4ba1f..c23eb1aa1 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -9,9 +9,11 @@ There are many ways to [contribute](/CONTRIBUTING.md) to this project. ## Project Structure -- `/internal/website` - faustjs.org +- `/internal/legacy.faustjs.org` - legacy faustjs documentation site - `/packages` - NPM packages +- `/examples` - Example projects - `/plugins` - WordPress Plugins +- `/scripts` - Packaging scripts ### NPM Packages @@ -71,7 +73,7 @@ composer run docker:start If desired, you may specify the WP_VERSION you'd like to run tests against: ```sh -WP_VERSION=5.5 composer run docker:start +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: @@ -83,13 +85,13 @@ docker-compose exec -e COVERAGE=1 wordpress init-testing-environment.sh Install and activate WP GraphQL: ```sh -docker-compose exec --workdir=/var/www/html/wp-content/plugins/faustwp --user=www-data wordpress wp plugin install wp-graphql --activate +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: ```sh -docker-compose exec -w /var/www/html/wp-content/plugins/faustwp wordpress composer test +docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) composer test ``` Finally, to remove the containers: @@ -135,8 +137,8 @@ FAUST_SECRET_KEY=00000000-0000-4000-8000-000000000001 1. Run `composer install` if you haven't already. 1. 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. - 1. Run `docker-compose exec --workdir=/var/www/html/wp-content/plugins/faustwp --user=www-data wordpress wp plugin install wp-graphql --activate` - 1. Run `docker-compose exec --workdir=/var/www/html/wp-content/plugins/faustwp --user=www-data wordpress wp db export tests/_data/dump.sql` + 1. Run `docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) wp plugin install wp-graphql --activate --allow-root` + 1. 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` 1. Copy `.env.testing.example` to `.env.testing`. 1. Run `vendor/bin/codecept run acceptance` to start the end-2-end tests. @@ -147,23 +149,12 @@ FAUST_SECRET_KEY=00000000-0000-4000-8000-000000000001 - [WPBrowser](https://wpbrowser.wptestkit.dev/) - WordPress framework wrapping Codeception for browser testing WordPress. -## Documentation - -The documentation site uses [Docusaurus](https://docusaurus.io/). Content lives primarily in MDX files under `internal/website/docs`. The following commands will get you up and running with a local copy of the docs. - -```sh -npm run docs:install # Install docs dependencies -npm run docs:build # Build the docs -npm run docs # Serve the site on http://localhost:3000 -``` - ## Git Workflows We have three notable branches: - `canary` - This branch has the latest changes - `main` - This branch is used to deploy changes to [faustjs.org](https://faustjs.org) -- `site-dev` - This branch is used to deploy to the staging site ### Code Changes/Feature Workflow @@ -178,23 +169,6 @@ We use the [feature branch workflow](https://www.atlassian.com/git/tutorials/com **Note**: We use Squash and Merge when merging pull requests into the `canary` branch. -### Staging Site Deployment - -When your feature branch includes changes to the documentation website, it's helpful to include a live preview link in the PR description. The [staging site](https://hcixzyt38dn5ak04xxcqc36lf.js.wpenginepowered.com/) is used for this purpose. You can deploy your changes to the staging site using the following steps: - -- Checkout and switch to the `site-dev` branch. -- Merge your feature branch into `site-dev`. -- Push your merge commit to `site-dev`. -- Within about 10 minutes, the docs changes from your feature branch should be visible on the [staging site](https://hcixzyt38dn5ak04xxcqc36lf.js.wpenginepowered.com/). - -### Prod Site Deployment - -The docs on faustjs.org are automatically built on pushes to `main`. Updating the docs on `main` will update faustjs.org within 10 minutes. - -After a successful release, a PR from `canary` to `main` is automatically created. Review and merge this PR to update faustjs.org. - -**Important**: Be sure to use the "Create a merge commit" option, and not "Squash and merge", as this can lead to [merge conflicts](https://medium.com/@guilhermerios/the-agony-and-the-ecstasy-of-git-squash-7f91c8da20af). - ## Deployment Developers with full GitHub repository access can create public releases. We use [Changesets](https://github.com/atlassian/changesets) to automate the versioning and deployment process for all of our packages and plugins. @@ -216,9 +190,9 @@ When you are ready to release, you should first create the new package and plugi - [ ] The plugin's readme.txt changelog has been updated with the latest 3 versions (Plugin versioning only) 3. Approve, then "Squash and merge" the "Version Packages" PR into `canary`. -### Publishing the @faustjs packages +### Publishing the @faustwp packages -The @faustjs packages are automatically published to NPM through a GitHub action once the "Version Packages" PR is merged. +The @faustwp packages are automatically published to NPM through a GitHub action once the "Version Packages" PR is merged. ### Publishing the FaustWP plugin @@ -226,11 +200,35 @@ Once the "Version Packages" PR is merged, create a new release on GitHub with a Once deployed, the updated packages and plugin will be visible here: -- https://www.npmjs.com/package/@faustjs/core -- https://www.npmjs.com/package/@faustjs/react -- https://www.npmjs.com/package/@faustjs/next +- https://www.npmjs.com/package/@faustwp/core +- https://www.npmjs.com/package/@faustwp/cli +- https://www.npmjs.com/package/@faustwp/experimental-app-router +- https://www.npmjs.com/package/@faustwp/block-editor-utils +- https://www.npmjs.com/package/@faustwp/blocks - https://plugins.trac.wordpress.org/browser/faustwp/tags -### Update the docs -After a release, remember to update the docs using the [Prod Site Deployment](#prod-site-deployment) process outlined above. +### Working with the Monorepo +This section offers guidance for developers working within the monorepo environment, which utilizes npm for package management. + +#### Navigation: + +* 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. + +#### Building and Deploying: + +* 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`. + +#### Additional Considerations: + +Use the `--workspaces` or `-w` flag to run a specific script command of a specified workspace. For example: + +```bash +$ npm run build -w examples/next/faustwp-getting-started +``` +It runs the `build` npm script for the `faustwp-getting-started` example project. +