From 62022dc1203bd38531fc992bbb5c0f6cf55c3c04 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 30 Oct 2024 18:33:23 -0400 Subject: [PATCH 1/3] add sync-docs README --- apps/svelte.dev/scripts/sync-docs/README.md | 82 +++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 apps/svelte.dev/scripts/sync-docs/README.md diff --git a/apps/svelte.dev/scripts/sync-docs/README.md b/apps/svelte.dev/scripts/sync-docs/README.md new file mode 100644 index 0000000000..ebbaaa7baf --- /dev/null +++ b/apps/svelte.dev/scripts/sync-docs/README.md @@ -0,0 +1,82 @@ +# sync-docs + +Documentation lives in external repos (at the time of writing, [`sveltejs/svelte`](https://github.com/sveltejs/svelte), [`sveltejs/kit`](https://github.com/sveltejs/kit) and [`sveltejs/cli`](https://github.com/sveltejs/cli), though the plan is to add others) and synced into this repo. + +The repos must be cloned (or linked — see [next section](#setup)) into the `apps/svelte.dev/repos` directory. + +## Setup + +For local development, it's recommended that you symlink the repos, so that you can see changes immediately then open a PR once you're happy with them: + +```bash +cd apps/svelte.dev +ln -s /path/to/wherever/you/cloned/sveltejs/svelte repos/svelte +ln -s /path/to/wherever/you/cloned/sveltejs/kit repos/kit +ln -s /path/to/wherever/you/cloned/sveltejs/cli repos/cli +``` + +I have no idea what the equivalent Windows command would be. + +## Syncing + +To run the `sync-docs` script locally: + +```bash +pnpm sync-docs +``` + +If you've symlinked the repos and want to watch for changes, you can use the `-w` command: + +```bash +pnpm sync-docs -w # or --watch, if you're fancy +``` + +To pull from the remote first (or clone it, if you don't have it symlinked/cloned locally already): + +```bash +pnpm sync-docs -p # or --pull +``` + +You can combine flags, and specify individual packages: + +```bash +pnpm sync-docs -pw kit cli +``` + +## Automation + +Changes to documentation in the source repos will trigger the [`sync-docs.yml`](../../../../.github/workflows/sync-docs.yml) workflow. This is possible because the repos in question have their own `sync-request.yml` workflow that dispatches a request to this repo. + +To set up a new repo, create a file in that repo called `.github/workflows/sync-request.yml` with the following contents: + +```yml +name: Dispatch sync request + +on: + push: + branches: + - main + +jobs: + dispatch: + runs-on: ubuntu-latest + steps: + - name: Repository Dispatch + uses: peter-evans/repository-dispatch@v3 + with: + token: ${{ secrets.SYNC_REQUEST_TOKEN }} + repository: sveltejs/svelte.dev + event-type: sync-request + client-payload: |- + { + "package": "cli" + } +``` + +You will need to add a `SYNC_REQUEST_TOKEN` to the repo. First, create a personal access token by going to https://github.com/settings/personal-access-tokens/new: + +- change the 'Resource owner' to `sveltejs` +- provide access to the `sveltejs/svelte.dev` repository +- under 'Repository permissions', change 'Contents' to 'Read and write' + +Then, go to `https://github.com///settings/secrets/actions`, click 'New repository secret' and paste in your newly generated personal access token. From a099138c013279d7cadb4eebe18ce7cf99046b08 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 30 Oct 2024 18:34:28 -0400 Subject: [PATCH 2/3] tweak --- apps/svelte.dev/scripts/sync-docs/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/apps/svelte.dev/scripts/sync-docs/README.md b/apps/svelte.dev/scripts/sync-docs/README.md index ebbaaa7baf..634f10af7c 100644 --- a/apps/svelte.dev/scripts/sync-docs/README.md +++ b/apps/svelte.dev/scripts/sync-docs/README.md @@ -69,10 +69,12 @@ jobs: event-type: sync-request client-payload: |- { - "package": "cli" + "package": "" } ``` +`YOUR_PACKAGE_NAME` corresponds to the entry in [index.ts](./index.ts). + You will need to add a `SYNC_REQUEST_TOKEN` to the repo. First, create a personal access token by going to https://github.com/settings/personal-access-tokens/new: - change the 'Resource owner' to `sveltejs` From 697974d366592d97a423bf83c0f24accd900565c Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 30 Oct 2024 19:06:51 -0400 Subject: [PATCH 3/3] link to README --- .github/workflows/sync-docs.yml | 2 +- apps/svelte.dev/scripts/sync-docs/README.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml index 9af58288c7..01bd5df484 100644 --- a/.github/workflows/sync-docs.yml +++ b/.github/workflows/sync-docs.yml @@ -24,6 +24,6 @@ jobs: with: commit-message: sync ${{ github.event.client_payload.package }} docs title: Sync `${{ github.event.client_payload.package }}` docs - body: This is an automated pull request + body: This is an automated pull request. See the [README](../tree/main/apps/svelte.dev/scripts/sync-docs/README.md) for more information branch: sync/${{ github.event.client_payload.package }} base: main diff --git a/apps/svelte.dev/scripts/sync-docs/README.md b/apps/svelte.dev/scripts/sync-docs/README.md index 634f10af7c..3ee19e2469 100644 --- a/apps/svelte.dev/scripts/sync-docs/README.md +++ b/apps/svelte.dev/scripts/sync-docs/README.md @@ -50,6 +50,7 @@ Changes to documentation in the source repos will trigger the [`sync-docs.yml`]( To set up a new repo, create a file in that repo called `.github/workflows/sync-request.yml` with the following contents: ```yml +# https://github.com/sveltejs/svelte.dev/blob/main/apps/svelte.dev/scripts/sync-docs/README.md name: Dispatch sync request on: