From 51bddee950b92c4cca102c3c42f76aa6967a4d2a Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Fri, 24 Oct 2025 15:14:34 -0400 Subject: [PATCH 1/7] refresh release process --- docs/configure/site/legacy-url-mappings.md | 2 +- docs/contribute/release-new-version.md | 43 +++++++++++++++++++--- 2 files changed, 38 insertions(+), 7 deletions(-) diff --git a/docs/configure/site/legacy-url-mappings.md b/docs/configure/site/legacy-url-mappings.md index 294e2cc81..2fae718fa 100644 --- a/docs/configure/site/legacy-url-mappings.md +++ b/docs/configure/site/legacy-url-mappings.md @@ -16,7 +16,7 @@ en/elasticsearch/reference/: ## Structure `stack anchor` -: Defines a reusable list of version strings for "stack" projects, e.g., [ '9.0+', '8.18', ... ]. +: Defines a reusable list of version strings for "stack" projects, e.g., [ '8.18', ... ]. `mappings` : A YAML mapping where each key is a legacy documentation URL path (like `en/apm/agent/java/`), and each value is a mapping with: diff --git a/docs/contribute/release-new-version.md b/docs/contribute/release-new-version.md index 56cb0496d..ac5263e23 100644 --- a/docs/contribute/release-new-version.md +++ b/docs/contribute/release-new-version.md @@ -8,6 +8,8 @@ Follow these steps to release a new documentation version. ::::{step} Update `versions.yml` +_This action can be performed by any member of the docs team. It's also [automated](https://github.com/elastic/docs-builder/actions/workflows/updatecli.yml) for many products._ + The `versions.yml` file defines the **base** (minimum) and **current** (latest) versions of each versioned product family. Example: @@ -28,6 +30,8 @@ Refer to [`versions.yml`](../configure/site/versions.md) for more information. ::::{step} (Optional) Update legacy URL mappings +_This action can be performed by any member of the docs team._ + If you're releasing a version older than the current `base`, or restoring support for a previously removed version, you may need to update the `legacy-url-mappings.yml` file. This file maps legacy URL paths (like `en/elasticsearch/reference/`) to the list of versions that exist at that path. @@ -35,21 +39,48 @@ This file maps legacy URL paths (like `en/elasticsearch/reference/`) to the list For example, to release the 8.19 version of the Elastic Stack, update the `stack` versions array to include the new version number: ```yml -- stack: &stack [ '9.0+', '8.19', '8.18', '8.17', ... ] +- stack: &stack [ '8.19', '8.18', '8.17', ... ] ``` +See [`legacy-url-mappings.yml`](../configure/site/legacy-url-mappings.md) for more information. + +:::: + +::::{step} Approve and merge the config change + +_This action must be performed by docs engineering._ + +Merge the `versions.yml` changes and any legacy URL mapping changes. + +Optionally, invoke the [Synchronize version & config updates](https://github.com/elastic/docs-internal-workflows/actions/workflows/update-assembler-version.yml) action manually on `docs-internal-workflows`, which opens two configuration update PRs: `staging` and `prod`. + +This action also runs on a cron job, but you can trigger it manually if needed. + :::{important} -The first version in the `mappings` list is treated as the "current" version in documentation version dropdown. +Do not merge the production PR until release day! ::: -See [`legacy-url-mappings.yml`](../configure/site/legacy-url-mappings.md) for more information. +:::: + +::::{step} After feature freeze: merge the config change to staging + +_This action must be performed by docs engineering._ + +Merge [the `staging` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). + +:::{important} +Do not merge the production PR until release day! +::: :::: -::::{step} Release a new version of docs-builder +::::{step} Release day: merge the config change to prod and release to production + +_This action must be performed by docs engineering. For most products, this change must be merged on release day._ -Version updates and content set additions require a release of docs-builder. -Contact the Docs Eng team for assistance. +1. Merge [the `prod` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). +2. Manually [invoke the release automation to production](https://github.com/elastic/docs-internal-workflows/actions/workflows/assembler-build.prod.yml). +3. Let the requester or docs release coordinator know the docs have been updated. :::: From 99a1bc27e04832050734fb3c121dc6aa4412da68 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 27 Oct 2025 09:45:12 -0400 Subject: [PATCH 2/7] missing assembler step --- docs/contribute/branching-strategy.md | 6 ++-- docs/contribute/release-new-version.md | 46 ++++++++++++++++++++++---- 2 files changed, 43 insertions(+), 9 deletions(-) diff --git a/docs/contribute/branching-strategy.md b/docs/contribute/branching-strategy.md index c68932826..9ecdc00ea 100644 --- a/docs/contribute/branching-strategy.md +++ b/docs/contribute/branching-strategy.md @@ -46,9 +46,9 @@ After it has been established that a repository should publish from a version br * Otherwise, keeping it set to `main` is also an option since this is where the content is initially developed and merged. This is the default. 4. In the assembler PR, add the `ci` label. After CI runs, confirm that the intended version branches are publishing to the link service. When links are being published as intended, they can be found at the following URL, where `repo` is your repo name and `branch` is your newly configured branch: - ```text - elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic///links.json - ``` + ```text + elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic///links.json + ``` 5. Rerun the `validate-assembler` check on the PR. 6. After checks pass and the docs engineering team approves, you can merge the PR. diff --git a/docs/contribute/release-new-version.md b/docs/contribute/release-new-version.md index ac5263e23..e410b4fab 100644 --- a/docs/contribute/release-new-version.md +++ b/docs/contribute/release-new-version.md @@ -4,9 +4,13 @@ When a new version of the Elastic Stack (or another versioned product) is releas Follow these steps to release a new documentation version. -:::::{stepper} +:::{tip} +The docs-builder PR steps can be bundled into a single PR. +::: + +:::::{stepper} -::::{step} Update `versions.yml` +::::{step} [docs-builder PR] Update `versions.yml` _This action can be performed by any member of the docs team. It's also [automated](https://github.com/elastic/docs-builder/actions/workflows/updatecli.yml) for many products._ @@ -24,11 +28,40 @@ versioning_systems: - Update the `current` version to reflect the newly released version. - Only update the `base` version if you're dropping support for an older version. -Refer to [`versions.yml`](../configure/site/versions.md) for more information. +Refer to [`versions.yml`](/configure/site/versions.md) for more information. + +:::: + +::::{step} [docs-builder PR] (Optional) Bump the version branch +_This action can be performed by any member of the docs team._ + +If you use the [tagged branching strategy](/contribute/branching-strategy.md), and your release corresponds with a new branch in the repository that holds your documentation, then you also need to bump the `current` and `next` branch in the docs configuration. + +This step is not always required, depending on your branching strategy. For example, if you only have branches for major versions of your product (e.g. 1 and 2), and you're already publishing your docs from the `1` branch, then you don't need to bump the version branch to release version 1.2 or 1.2.3 of your documentation. + +1. In `assembler.yml`, specifying the new `current` and `next` branches for your repository: + + ```yml + your-product: + current: 1.1 + next: 1.2 + ``` + + Some people use `main` or `master` for their `next` branch. In this case, the `next` value doesn't need to be changed. + +2. Tag the PR with the `ci` label. After CI runs, confirm that the intended version branches are publishing to the link service. When links are being published as intended, they can be found at the following URL, where repo is your repo name and branch is your newly configured branch: + + ``` + elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic///links.json + ``` + +3. Rerun the `validate-assembler` check on the PR. + +[Learn more about changing the published branch](/contribute/branching-strategy.md#how-to-change-the-published-branch). :::: -::::{step} (Optional) Update legacy URL mappings +::::{step} [docs-builder PR] (Optional) Update legacy URL mappings _This action can be performed by any member of the docs team._ @@ -46,11 +79,11 @@ See [`legacy-url-mappings.yml`](../configure/site/legacy-url-mappings.md) for mo :::: -::::{step} Approve and merge the config change +::::{step} [docs-builder PR] Approve and merge the config change _This action must be performed by docs engineering._ -Merge the `versions.yml` changes and any legacy URL mapping changes. +Merge the `versions.yml` changes and any assembler and legacy URL mapping changes. Optionally, invoke the [Synchronize version & config updates](https://github.com/elastic/docs-internal-workflows/actions/workflows/update-assembler-version.yml) action manually on `docs-internal-workflows`, which opens two configuration update PRs: `staging` and `prod`. @@ -91,3 +124,4 @@ Cumulative documentation relies on version metadata through `applies_to` blocks, Check the built output to ensure `applies_to` changes are correctly rendering. :::: +::::: From 098efc2c5a7a3193922712d7efb01f5c74c17bb6 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 28 Oct 2025 12:24:15 -0400 Subject: [PATCH 3/7] jan feedback --- docs/contribute/release-new-version.md | 29 +++++++++++++++++--------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/contribute/release-new-version.md b/docs/contribute/release-new-version.md index e410b4fab..83c5db574 100644 --- a/docs/contribute/release-new-version.md +++ b/docs/contribute/release-new-version.md @@ -2,6 +2,17 @@ When a new version of the Elastic Stack (or another versioned product) is released, the docs site must be updated to recognize it. This process primarily involves updating version metadata in the shared site configuration. +## Who needs to be involved + +Generally, each release requires the following people: + +* A member of the **docs team** to make the config changes in a docs-builder PR +* A member of the **docs engineering** or **docs tech leads** team to support publishing those changes to staging and prod. + +Before you start your release, you should identify who from each of these teams will facilitate the release. + +## Release process + Follow these steps to release a new documentation version. :::{tip} @@ -79,15 +90,13 @@ See [`legacy-url-mappings.yml`](../configure/site/legacy-url-mappings.md) for mo :::: -::::{step} [docs-builder PR] Approve and merge the config change - -_This action must be performed by docs engineering._ +::::{step} [docs-builder PR] Merge the config change -Merge the `versions.yml` changes and any assembler and legacy URL mapping changes. +Merge the `versions.yml` changes and any assembler and legacy URL mapping changes. Anyone from the docs team can merge the PR, but it must be approved by docs engineering or docs tech leads. -Optionally, invoke the [Synchronize version & config updates](https://github.com/elastic/docs-internal-workflows/actions/workflows/update-assembler-version.yml) action manually on `docs-internal-workflows`, which opens two configuration update PRs: `staging` and `prod`. +Optionally, docs engineering can invoke the [Synchronize version & config updates](https://github.com/elastic/docs-internal-workflows/actions/workflows/update-assembler-version.yml) action manually on `docs-internal-workflows`, which opens two configuration update PRs: `staging` and `prod`. -This action also runs on a cron job, but you can trigger it manually if needed. +This action also runs on a cron job, but can be triggered manually if the change is time-sensitive. :::{important} Do not merge the production PR until release day! @@ -97,9 +106,9 @@ Do not merge the production PR until release day! ::::{step} After feature freeze: merge the config change to staging -_This action must be performed by docs engineering._ +_This action must be performed by docs engineering or docs tech leads._ -Merge [the `staging` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). +Approve and merge [the `staging` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). :::{important} Do not merge the production PR until release day! @@ -109,9 +118,9 @@ Do not merge the production PR until release day! ::::{step} Release day: merge the config change to prod and release to production -_This action must be performed by docs engineering. For most products, this change must be merged on release day._ +_This action must be performed by docs engineering or docs tech leads. For most products, this change must be merged on release day._ -1. Merge [the `prod` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). +1. Approve and merge [the `prod` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). 2. Manually [invoke the release automation to production](https://github.com/elastic/docs-internal-workflows/actions/workflows/assembler-build.prod.yml). 3. Let the requester or docs release coordinator know the docs have been updated. From 9fd8f55eed0c6521653197abbcfefd3428c585e3 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 28 Oct 2025 13:00:53 -0400 Subject: [PATCH 4/7] Apply suggestions from code review --- docs/contribute/release-new-version.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/contribute/release-new-version.md b/docs/contribute/release-new-version.md index 83c5db574..086cc8985 100644 --- a/docs/contribute/release-new-version.md +++ b/docs/contribute/release-new-version.md @@ -108,7 +108,8 @@ Do not merge the production PR until release day! _This action must be performed by docs engineering or docs tech leads._ -Approve and merge [the `staging` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). +1. Approve and merge [the `staging` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). +2. Optionally, manually [invoke the release automation to staging](https://github.com/elastic/docs-internal-workflows/actions/workflows/assembler-build.staging.yml). :::{important} Do not merge the production PR until release day! @@ -121,7 +122,7 @@ Do not merge the production PR until release day! _This action must be performed by docs engineering or docs tech leads. For most products, this change must be merged on release day._ 1. Approve and merge [the `prod` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). -2. Manually [invoke the release automation to production](https://github.com/elastic/docs-internal-workflows/actions/workflows/assembler-build.prod.yml). +2. Manually [invoke the release automation to production](https://github.com/elastic/docs-internal-workflows/actions/workflows/assembler-build.prod.yml). Monitor it to make sure that it's green. 3. Let the requester or docs release coordinator know the docs have been updated. :::: From 9a576af83d0279cd6b5a9cd35de0125b51565201 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 28 Oct 2025 13:04:19 -0400 Subject: [PATCH 5/7] clarity --- docs/contribute/release-new-version.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/contribute/release-new-version.md b/docs/contribute/release-new-version.md index 086cc8985..d300e8d81 100644 --- a/docs/contribute/release-new-version.md +++ b/docs/contribute/release-new-version.md @@ -111,6 +111,10 @@ _This action must be performed by docs engineering or docs tech leads._ 1. Approve and merge [the `staging` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). 2. Optionally, manually [invoke the release automation to staging](https://github.com/elastic/docs-internal-workflows/actions/workflows/assembler-build.staging.yml). + This action also runs on a cron job, but can be triggered manually if the change is time-sensitive. + +If you need to release to production right away, make sure that the workflow run is green before proceeding. + :::{important} Do not merge the production PR until release day! ::: From 34581f358cc06c0fe0900827348f1404ca3932f0 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 28 Oct 2025 13:08:54 -0400 Subject: [PATCH 6/7] alerting window --- docs/contribute/release-new-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/release-new-version.md b/docs/contribute/release-new-version.md index d300e8d81..30a86a06c 100644 --- a/docs/contribute/release-new-version.md +++ b/docs/contribute/release-new-version.md @@ -113,7 +113,7 @@ _This action must be performed by docs engineering or docs tech leads._ This action also runs on a cron job, but can be triggered manually if the change is time-sensitive. -If you need to release to production right away, make sure that the workflow run is green before proceeding. +If you need to release to production right away, make sure that the workflow run is green and wait for 10 to 15 minutes for any alerts to be raised. Docs tech leads should check with docs eng before proceeding. :::{important} Do not merge the production PR until release day! From 1ba27fe9528bb68298f176a4e2e707e33b93629a Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 13 Nov 2025 13:56:27 -0500 Subject: [PATCH 7/7] fixed incorrect steps --- docs/contribute/release-new-version.md | 47 ++++++++++++++------------ 1 file changed, 26 insertions(+), 21 deletions(-) diff --git a/docs/contribute/release-new-version.md b/docs/contribute/release-new-version.md index 056862a4f..9eb5022b6 100644 --- a/docs/contribute/release-new-version.md +++ b/docs/contribute/release-new-version.md @@ -10,18 +10,24 @@ When a new version of the Elastic Stack (or another versioned product) is releas Generally, each release requires the following people: -* A member of the **docs team** to make the config changes in a docs-builder PR -* A member of the **docs engineering** or **docs tech leads** team to support publishing those changes to staging and prod. +* A member of the **docs team** to perform release prep +* A member of the **docs engineering** team to support publishing those changes to staging and prod. Before you start your release, you should identify who from each of these teams will facilitate the release. ## Release process -Follow these steps to release a new documentation version. +Follow these steps to release a new documentation version. There are two phases to releasing a new version: -:::{tip} -The docs-builder PR steps can be bundled into a single PR. -::: +* **Release prep**: Prepare the relevant docs-builder changes. This can be done anytime before release day, and can be performed by any member of the docs team. +* **Release day activities**: Merge your changes and push them to our staging and production environments. These steps must be performed on release day, and require support from docs engineering. + + +### Release prep + +Anytime before release day, you can prepare the release-related changes. These changes can be bundled into a single PR. + +Do not merge these changes until release day. :::::{stepper} @@ -94,40 +100,39 @@ See [`legacy-url-mappings.yml`](../configure/site/legacy-url-mappings.md) for mo :::: +::::: + +### Release day activities + +Merge your changes and push them to our staging and production environments on release day. + +:::::{stepper} + ::::{step} [docs-builder PR] Merge the config change Merge the `versions.yml` changes and any assembler and legacy URL mapping changes. Anyone from the docs team can merge the PR, but it must be approved by docs engineering or docs tech leads. -Optionally, docs engineering can invoke the [Synchronize version & config updates](https://github.com/elastic/docs-internal-workflows/actions/workflows/update-assembler-version.yml) action manually on `docs-internal-workflows`, which opens two configuration update PRs: `staging` and `prod`. +Optionally, docs engineering or docs tech leads can invoke the [Synchronize version & config updates](https://github.com/elastic/docs-internal-workflows/actions/workflows/update-assembler-version.yml) action manually on `docs-internal-workflows`, which opens two configuration update PRs: `staging` and `prod`. This action also runs on a cron job, but can be triggered manually if the change is time-sensitive. - -:::{important} -Do not merge the production PR until release day! -::: - :::: -::::{step} After feature freeze: merge the config change to staging +::::{step} Merge the config change to staging -_This action must be performed by docs engineering or docs tech leads._ +_This action must be performed by docs engineering._ 1. Approve and merge [the `staging` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). 2. Optionally, manually [invoke the release automation to staging](https://github.com/elastic/docs-internal-workflows/actions/workflows/assembler-build.staging.yml). This action also runs on a cron job, but can be triggered manually if the change is time-sensitive. -If you need to release to production right away, make sure that the workflow run is green and wait for 10 to 15 minutes for any alerts to be raised. Docs tech leads should check with docs eng before proceeding. - -:::{important} -Do not merge the production PR until release day! -::: +Before you merge the config change to prod in the next step, make sure that the workflow run is green and wait for 10 to 15 minutes for any alerts to be raised. :::: -::::{step} Release day: merge the config change to prod and release to production +::::{step} Merge the config change to prod and release to production -_This action must be performed by docs engineering or docs tech leads. For most products, this change must be merged on release day._ +_This action must be performed by docs engineering._ 1. Approve and merge [the `prod` configuration update PR](https://github.com/elastic/docs-internal-workflows/pulls). 2. Manually [invoke the release automation to production](https://github.com/elastic/docs-internal-workflows/actions/workflows/assembler-build.prod.yml). Monitor it to make sure that it's green.