From ec8048bc7a8dcfba797999a1227ebe37c2faba73 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Tue, 25 Feb 2025 07:55:49 -0800 Subject: [PATCH 1/6] Update move-ref-docs.md --- docs/migration/guide/move-ref-docs.md | 30 +++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/migration/guide/move-ref-docs.md b/docs/migration/guide/move-ref-docs.md index 3c19161fa..74c4d3017 100644 --- a/docs/migration/guide/move-ref-docs.md +++ b/docs/migration/guide/move-ref-docs.md @@ -95,6 +95,8 @@ Example commit: [#398/commit](https://github.com/elastic/apm-agent-android/pull/ ### Step 3: Add the new CI checks +There are two CI checks to add: + **docs-build** * The file to add: [`github/workflows/docs-build.yml`](https://github.com/elastic/docs-content/blob/main/.github/workflows/docs-build.yml) * The path and name of the new file: `.github/workflows/docs-build.yml` @@ -103,6 +105,34 @@ Example commit: [#398/commit](https://github.com/elastic/apm-agent-android/pull/ * The file to add: [`.github/workflows/docs-cleanup.yml`](https://github.com/elastic/docs-content/blob/main/.github/workflows/docs-cleanup.yml) * The path and name of the new file: `.github/workflows/docs-cleanup.yml` +In the `docs-build.yml` file, specify the directory in which the check should run using the `path-pattern` parameter. For example, if you've added docs to the `/docs` dir, add the following lines to the `docs-preview` job: + +```yml + with: + path-pattern: docs/** +``` + +In context: + +```yml +jobs: + docs-preview: + uses: elastic/docs-builder/.github/workflows/preview-build.yml + + with: + path-pattern: docs/** <1> + + permissions: + id-token: write + deployments: write + contents: read + pull-requests: read +``` + +1. The path to the docs directory + +Learn more about these ci checks in [](./how-to-set-up-docs-previews). + Example commit: [#398/commit](https://github.com/elastic/apm-agent-android/pull/398/commits/e869386bbf4af23d51432226f1fd3935d233e43d) ### Step 4: Delete the asciidoc warning From a0216a90ebb9b8f5d709520d395b8cdc069ecd25 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Tue, 25 Feb 2025 08:12:05 -0800 Subject: [PATCH 2/6] Update move-ref-docs.md --- docs/migration/guide/move-ref-docs.md | 54 +++++++++++++++++---------- 1 file changed, 35 insertions(+), 19 deletions(-) diff --git a/docs/migration/guide/move-ref-docs.md b/docs/migration/guide/move-ref-docs.md index 74c4d3017..73c505b0c 100644 --- a/docs/migration/guide/move-ref-docs.md +++ b/docs/migration/guide/move-ref-docs.md @@ -98,42 +98,58 @@ Example commit: [#398/commit](https://github.com/elastic/apm-agent-android/pull/ There are two CI checks to add: **docs-build** -* The file to add: [`github/workflows/docs-build.yml`](https://github.com/elastic/docs-content/blob/main/.github/workflows/docs-build.yml) -* The path and name of the new file: `.github/workflows/docs-build.yml` +Add a file named `docs-build.yml` at `.github/workflows/docs-build.yml`. The contents of this file are below: -**docs-cleanup** -* The file to add: [`.github/workflows/docs-cleanup.yml`](https://github.com/elastic/docs-content/blob/main/.github/workflows/docs-cleanup.yml) -* The path and name of the new file: `.github/workflows/docs-cleanup.yml` +```yml +name: docs-build -In the `docs-build.yml` file, specify the directory in which the check should run using the `path-pattern` parameter. For example, if you've added docs to the `/docs` dir, add the following lines to the `docs-preview` job: +on: + push: + branches: + - main + pull_request_target: ~ -```yml +jobs: + docs-preview: + uses: elastic/docs-builder/.github/workflows/preview-build.yml@main with: path-pattern: docs/** + permissions: + deployments: write + id-token: write + contents: read + pull-requests: read ``` -In context: +Learn more about this file: [`docs-build.yml`](./how-to-set-up-docs-previews.md#build). + +:::{important} +If the documentation you are adding will not live in the `/docs/*` dir of the repository, you must update the `path-pattern` appropriately. Please reach out in #docs-team if you need help with this. +::: + +**docs-cleanup** +Add a file named `docs-cleanup.yml` at `.github/workflows/docs-cleanup.yml`. The contents of this file are below: ```yml -jobs: - docs-preview: - uses: elastic/docs-builder/.github/workflows/preview-build.yml +name: docs-cleanup - with: - path-pattern: docs/** <1> +on: + pull_request_target: + types: + - closed +jobs: + docs-preview: + uses: elastic/docs-builder/.github/workflows/preview-cleanup.yml@main permissions: + contents: none id-token: write deployments: write - contents: read - pull-requests: read ``` -1. The path to the docs directory - -Learn more about these ci checks in [](./how-to-set-up-docs-previews). +Learn more about this file: [`docs-cleanup.yml`](./how-to-set-up-docs-previews.md#cleanup) -Example commit: [#398/commit](https://github.com/elastic/apm-agent-android/pull/398/commits/e869386bbf4af23d51432226f1fd3935d233e43d) +Example PR: [#398](https://github.com/elastic/apm-agent-android/pull/398) ### Step 4: Delete the asciidoc warning From 5d12a89bcf6275672078455f86c28f694a52ea3e Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Tue, 25 Feb 2025 08:15:20 -0800 Subject: [PATCH 3/6] Apply suggestions from code review --- docs/migration/guide/move-ref-docs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/migration/guide/move-ref-docs.md b/docs/migration/guide/move-ref-docs.md index 73c505b0c..a1383bfe9 100644 --- a/docs/migration/guide/move-ref-docs.md +++ b/docs/migration/guide/move-ref-docs.md @@ -97,7 +97,7 @@ Example commit: [#398/commit](https://github.com/elastic/apm-agent-android/pull/ There are two CI checks to add: -**docs-build** +**`docs-build.yml`** Add a file named `docs-build.yml` at `.github/workflows/docs-build.yml`. The contents of this file are below: ```yml @@ -127,7 +127,7 @@ Learn more about this file: [`docs-build.yml`](./how-to-set-up-docs-previews.md# If the documentation you are adding will not live in the `/docs/*` dir of the repository, you must update the `path-pattern` appropriately. Please reach out in #docs-team if you need help with this. ::: -**docs-cleanup** +**`docs-cleanup.yml`** Add a file named `docs-cleanup.yml` at `.github/workflows/docs-cleanup.yml`. The contents of this file are below: ```yml From 9d18620963dda773dae59000cad6781824bd183e Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Tue, 25 Feb 2025 08:24:37 -0800 Subject: [PATCH 4/6] Update docs/migration/guide/move-ref-docs.md --- docs/migration/guide/move-ref-docs.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/migration/guide/move-ref-docs.md b/docs/migration/guide/move-ref-docs.md index a1383bfe9..8e7e723fe 100644 --- a/docs/migration/guide/move-ref-docs.md +++ b/docs/migration/guide/move-ref-docs.md @@ -104,6 +104,7 @@ Add a file named `docs-build.yml` at `.github/workflows/docs-build.yml`. The con name: docs-build on: + merge_group push: branches: - main From 64024fceb9430861a40ba332b7349e3157c13a69 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Tue, 25 Feb 2025 08:27:17 -0800 Subject: [PATCH 5/6] Update docs/migration/guide/move-ref-docs.md Co-authored-by: Jan Calanog --- docs/migration/guide/move-ref-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration/guide/move-ref-docs.md b/docs/migration/guide/move-ref-docs.md index 8e7e723fe..402dbe94a 100644 --- a/docs/migration/guide/move-ref-docs.md +++ b/docs/migration/guide/move-ref-docs.md @@ -104,7 +104,7 @@ Add a file named `docs-build.yml` at `.github/workflows/docs-build.yml`. The con name: docs-build on: - merge_group + merge_group: ~ push: branches: - main From 251b09ef20cbe57936b23c90b1fca1de22236ac8 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Tue, 25 Feb 2025 08:28:06 -0800 Subject: [PATCH 6/6] move to bottom so it's alligned with pr target --- docs/migration/guide/move-ref-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration/guide/move-ref-docs.md b/docs/migration/guide/move-ref-docs.md index 402dbe94a..b5c9933c2 100644 --- a/docs/migration/guide/move-ref-docs.md +++ b/docs/migration/guide/move-ref-docs.md @@ -104,11 +104,11 @@ Add a file named `docs-build.yml` at `.github/workflows/docs-build.yml`. The con name: docs-build on: - merge_group: ~ push: branches: - main pull_request_target: ~ + merge_group: ~ jobs: docs-preview: