From 1c2db2f8c7e0d32633524efbbefb892b2a847cc4 Mon Sep 17 00:00:00 2001 From: James Amner Date: Mon, 13 Jan 2025 12:05:04 +0000 Subject: [PATCH] [BWP-117] Retype Setup --- .github/workflows/docs.yml | 26 +++++++ docs/index.md | 8 --- docs/{skeleton.md => skeleton/index.md} | 15 ----- docs/update-wp-packages.md | 90 ------------------------- packages/deps-auto-update/readme.md | 48 +++++++++++-- retype.yml | 12 ++++ 6 files changed, 81 insertions(+), 118 deletions(-) create mode 100644 .github/workflows/docs.yml delete mode 100644 docs/index.md rename docs/{skeleton.md => skeleton/index.md} (73%) delete mode 100644 docs/update-wp-packages.md create mode 100644 retype.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..d3f40073 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,26 @@ +name: Publish Docs +on: + workflow_dispatch: + push: + branches: + - main + +jobs: + publish: + name: Publish to retype branch + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + name: Checkout + - uses: actions/setup-dotnet@v1 + name: Setup + with: + dotnet-version: 7.0.x + - uses: retypeapp/action-build@latest + name: Build + - uses: retypeapp/action-github-pages@latest + name: Publish + with: + update-branch: true diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 027f7908..00000000 --- a/docs/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# WP Packages - -Contents: -- [Project Skeleton](./skeleton.md) -- [Editor Tools](../packages/editor-tools/README.md) -- [Iconography](../packages/iconography/README.md) -- [Feature Flags](../packages/feature-flags/README.md) -- [Updating Dependancies](./update-wp-packages.md) \ No newline at end of file diff --git a/docs/skeleton.md b/docs/skeleton/index.md similarity index 73% rename from docs/skeleton.md rename to docs/skeleton/index.md index a8c1ea36..c167e0d1 100644 --- a/docs/skeleton.md +++ b/docs/skeleton/index.md @@ -58,18 +58,3 @@ bin/docker/wp user update admin --user_pass=your_password_here > You can read more about all of these features in [this post on the Box UK blog](https://www.boxuk.com/insight/how-we-develop-wordpress-sites/). -## Documentation - -- [Docker](./skeleton/docker-setup.md) -- [Fixtures](./skeleton/fixtures.md) -- [HTTPS](./skeleton/https.md) -- [Non-Docker Setup](./skeleton/non-docker-setup.md) -- [Patched Plugins](./skeleton/patched-plugins.md) -- [Premium Plugins](./skeleton/premium-plugins.md) -- [PHP Versions](./skeleton/php-versions.md) -- [Quickstart](./skeleton/quickstart.md) -- [Setup Initial State](./skeleton/setup-initial-state.md) -- [Testing](./skeleton/testing.md) -- [Troubleshooting](./skeleton/troubleshooting.md) -- [Usage](./skeleton/usage.md) -- [WP-VIP](./skeleton/vip.md) diff --git a/docs/update-wp-packages.md b/docs/update-wp-packages.md deleted file mode 100644 index 67f1cdf6..00000000 --- a/docs/update-wp-packages.md +++ /dev/null @@ -1,90 +0,0 @@ -# Updating WP Packages - -WordPress bundles versions of certain dependancies from WordPress core, and when we use `wp-scripts` to compile our packages it strips out the versions we've defined in `package.json` and instead relies on the versions bundled by WordPress. This means that you should be using the same dependancy version as WordPress provides during development to make sure that you're building compatible code. - -Because of this, you should not allow `dependabot` or other automated solutions to update an `@wordpress/` packages in your node package. Instead, the `wp-scripts` `packages-update` command should be used. - -## Setting up your project - -You should define a `WORDPRESS_VERSION` env value in your `.env` file. This should be the major and minor version ie, `6.6` or `7.2`. -Your `package.json` file should include a script which handles updating the the WP packages to the given version. If you're using -`turbo` to manage a mono-repo, this would typically look like: -```jsonc package.json -{ - // ... rest of your package - "scripts": { - // ...any other scripts - "packages-update": "turbo run packages-update --concurrency=1 -- -- --dist-tag=wp-$WORDPRESS_VERSION", - } -} -``` - -Without `turbo` the command would look similar but without the concurrency and the extra `--` args. - -## Setting up Dependabot - -You should disable dependabot from updating the included deps, by adding the following to your `dependabot.yml` file: -```yml - # NodeJS Deps - - package-ecosystem: npm - directory: "/" - registries: "*" - schedule: - interval: daily - ignore: - # Ignore updates to the WordPress packages, we'll handle those manually. - - dependency-name: "@wordpress/*" - - dependency-name: "react" - - dependency-name: "react-dom" -``` - -## Setting up workflow/automation - -We have a script provided which can automate updating the WP Packages as the WP core version updates. - -You can add a file to your `.github/workflows` directory which automates updates. You will need to define the `WORDPRESS_VERSION` in the GitHub repo. You will likely require administrator access to the repo to do this, so raise to a senior/principal dev if you cannot do this. - -```yml -name: Update WP Deps - -on: - schedule: - - cron: '0 3 * * *' - workflow_dispatch: - -env: - WORDPRESS_VERSION: ${{ vars.WORDPRESS_VERSION }} - -jobs: - update-deps: - runs-on: ubuntu-latest - steps: - - name: Run Update - uses: './.github/wp-packages' - with: - WP_VERSION: ${{ env.WORDPRESS_VERSION }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` - -Broadly this script sets up node using an `.nvmrc` file, then runs `npm run packages-update`. If there's changes, it creates or updates a PR as appropriate. - -After the PR is created, you may need to manually trigger any test-suites you have. Any PRs created by automations do not typically trigger tests/workflows to run (to prevent recursion), so manually triggering is required. You can add a step to the workflow above to trigger. -```yml - - name: Run Tests - uses: actions/github-script@v3 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - script: | - await github.actions.createWorkflowDispatch({ - owner: context.repo.owner, - repo: context.repo.repo, - workflow_file: 'test-php.yml', - ref: deps/wp-packages/wp-${{ env.WORDPRESS_VERSION }} - }); - await github.actions.createWorkflowDispatch({ - owner: context.repo.owner, - repo: context.repo.repo, - workflow_file: 'test-js.yml', - ref: deps/wp-packages/wp-${{ env.WORDPRESS_VERSION }} - }); -``` diff --git a/packages/deps-auto-update/readme.md b/packages/deps-auto-update/readme.md index 9beae7f0..a9c66663 100644 --- a/packages/deps-auto-update/readme.md +++ b/packages/deps-auto-update/readme.md @@ -14,9 +14,6 @@ on: - cron: '0 3 * * *' workflow_dispatch: -env: - WORDPRESS_VERSION: ${{ vars.WORDPRESS_VERSION }} - jobs: update-deps: runs-on: ubuntu-latest @@ -30,11 +27,52 @@ jobs: - name: Run Update uses: 'boxuk/wp-deps-auto-update@main' with: - WP_VERSION: ${{ env.WORDPRESS_VERSION }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` -You could use another technique to determine the WordPress version, such as reading from your `composer.json` file. + +# Setting up your Project for WP Packages + +WordPress bundles versions of certain dependancies from WordPress core, and when we use `wp-scripts` to compile our packages it strips out the versions we've defined in `package.json` and instead relies on the versions bundled by WordPress. This means that you should be using the same dependancy version as WordPress provides during development to make sure that you're building compatible code. + +Because of this, you should not allow `dependabot` or other automated solutions to update an `@wordpress/` packages in your node package. Instead, the `wp-scripts` `packages-update` command should be used. + +## Setting up your project + +You should define a `WORDPRESS_VERSION` env value in your `.env` file. This should be the major and minor version ie, `6.6` or `7.2`. + +> You could use another technique to determine the WordPress version, such as reading from your `composer.json` file. + +Your `package.json` file should include a script which handles updating the the WP packages to the given version. If you're using +`turbo` to manage a mono-repo, this would typically look like: +```jsonc package.json +{ + // ... rest of your package + "scripts": { + // ...any other scripts + "packages-update": "turbo run packages-update --concurrency=1 -- -- --dist-tag=wp-$WORDPRESS_VERSION", + } +} +``` + +Without `turbo` the command would look similar but without the concurrency and the extra `--` args. + +## Setting up Dependabot + +You should disable dependabot from updating the included deps, by adding the following to your `dependabot.yml` file: +```yml + # NodeJS Deps + - package-ecosystem: npm + directory: "/" + registries: "*" + schedule: + interval: daily + ignore: + # Ignore updates to the WordPress packages, we'll handle those manually. + - dependency-name: "@wordpress/*" + - dependency-name: "react" + - dependency-name: "react-dom" +``` ## Contributing diff --git a/retype.yml b/retype.yml new file mode 100644 index 00000000..864283a4 --- /dev/null +++ b/retype.yml @@ -0,0 +1,12 @@ +input: . +output: .retype +url: https://boxuk.github.io/wp-packages +branding: + title: BoxUK Wordpress Packages + label: Docs +exclude: + - .git + - packages/vendor + - node_modules/ + - tests/ + - hooks/