From 97f809d638521f9d236a623d599b864f9eaf0a01 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Thu, 22 May 2025 10:36:05 +0200 Subject: [PATCH 1/4] Update versioning docs with deployment models and CI details Clarified content sources, deployment models (continuous and tagged), and their configurations in the versioning documentation. Added instructions for CI setup and repository onboarding, providing guidance for smoother integration and timing control of documentation deployment. --- .../guide/how-to-set-up-docs-previews.md | 10 +- docs/migration/guide/move-ref-docs.md | 3 + docs/migration/versioning.md | 108 +++++++++++++++++- 3 files changed, 116 insertions(+), 5 deletions(-) diff --git a/docs/migration/guide/how-to-set-up-docs-previews.md b/docs/migration/guide/how-to-set-up-docs-previews.md index 7a367bed1..24dc7c0af 100644 --- a/docs/migration/guide/how-to-set-up-docs-previews.md +++ b/docs/migration/guide/how-to-set-up-docs-previews.md @@ -28,13 +28,14 @@ on: push: branches: - main <1> + - '\d+.\d+' <2> pull_request_target: ~ jobs: docs-preview: - uses: elastic/docs-builder/.github/workflows/preview-build.yml <2> + uses: elastic/docs-builder/.github/workflows/preview-build.yml <3> with: - path-pattern: docs/** <3> + path-pattern: docs/** <4> permissions: id-token: write deployments: write @@ -43,8 +44,9 @@ jobs: ``` 1. You need to adjust this to your default branch. E.g `main`, `master`, etc. -2. Reusable workflow: [elastic/docs-builder/.github/workflows/preview-build.yml](https://github.com/elastic/docs-builder/blob/main/.github/workflows/preview-build.yml) -3. This should be the path to your docs folder. +2. Optional, a match for the branch you wish to publish to production if different from the first. +3. Reusable workflow: [elastic/docs-builder/.github/workflows/preview-build.yml](https://github.com/elastic/docs-builder/blob/main/.github/workflows/preview-build.yml) +4. This should be the path to your `docs` folder. ::: diff --git a/docs/migration/guide/move-ref-docs.md b/docs/migration/guide/move-ref-docs.md index 4cd947783..2a21f4826 100644 --- a/docs/migration/guide/move-ref-docs.md +++ b/docs/migration/guide/move-ref-docs.md @@ -115,6 +115,7 @@ on: push: branches: - main + - '\d+.\d+' <1> pull_request_target: ~ merge_group: ~ @@ -130,6 +131,8 @@ jobs: pull-requests: read ``` +1. Optional match for version branches if you do not wish to publish to production from `main`. + Learn more about this file: [`docs-build.yml`](./how-to-set-up-docs-previews.md#build). :::{important} diff --git a/docs/migration/versioning.md b/docs/migration/versioning.md index 4b7106344..489cf5a20 100644 --- a/docs/migration/versioning.md +++ b/docs/migration/versioning.md @@ -7,4 +7,110 @@ To ensure a seamless experience for users and contributors, the new versioning a * Context awareness — Each page explicitly states the context it applies to, including relevant deployment types (e.g., Elastic Cloud Hosted and Elastic Cloud Serverless) and versions. Context clarity ensures users know if the content is applicable to their environment. When users land on a Docs page that doesn’t apply to their version or deployment type, clear cues and instructions will guide them to the appropriate content. * Simplified contributor workflow — For pages that apply to multiple versions or deployment types, we’ve optimized the contributor experience by reducing complexity. Contributors can now manage multi-context content with ease, without duplicating information or navigating confusing workflows. -For versioning plan details, check [Docs Versioning plan](https://docs.google.com/presentation/d/1rHl0ia0ZkLHPLAYE5522CTDoatqwAxwAo29_etStPW8/edit?usp=sharing). To learn how to call out versioning differences in docs-builder, see [product availability](../syntax/applies.md). \ No newline at end of file +For versioning plan details, check [Docs Versioning plan](https://docs.google.com/presentation/d/1rHl0ia0ZkLHPLAYE5522CTDoatqwAxwAo29_etStPW8/edit?usp=sharing). To learn how to call out versioning differences in docs-builder, see [product availability](../syntax/applies.md). + + +# Content Sources + +To support multiple deployment models for different repositories, we support the concept of a content source. + +Next +: The source for the upcoming documentation. + +Current +: The source for the active documentation. + + +Our publish environments are connected to a single content source. + +| Publish Environment | Content Source | +|---------------------|----------------| +| Production | `Current` | +| Staging | `Current` | +| Edge | `Next` | + +This allows you as an owner of a repository to choose two different deployment models. + +# Deployment models. + +The new documentation system supports 2 deployment models. + +Continuous deployment. +: This is the default where a repositories `main` or `master` branch is continuously deployed to production. + +Tagged deployment +: Allows you to 'tag' a single git reference (typically a branch) as `current` which will be used to deploy to production. + Allowing you to control the timing of when new documentation should go live. + + +## Continuous Deployment + +This is the default. To get started, follow our [guide](guide/index.md) to set up the new docs folder structure and CI configuration + +Once setup ensure the repository is added to our `assembler.yml` under `references`. + +For example say you want to onboard `elastic/my-repository` into the production build: + +```yaml +references: + my-repository: +``` + +Is equivalent to specifying. + +```yaml +references: + my-repository: + next: main + current: main +``` + +% TODO we need navigation.yml docs +Once the repository is added, its navigation still needs to be injected into to global site navigation. + +## Tagged Deployment + +If you want to have more control over the timing of when your docs go live to production. Configure the repository +in our `assembler.yml` to have a fixed git reference (typically a branch) deploy the `current` content source to production. + +```yaml +references: + my-other-repository: + next: main + current: 9.0 +``` + +:::{note} +In order for `9.0` to be onboarded it needs to first follow our [migration guide](guide/index.md) and have our documentation CI integration setup. +Our CI integration checks will block until `current` is successfully configured +::: + +### CI Configuration + +To ensure [tagged deployments](#tagged-deployment) can be onboarded correctly, our CI integration needs to have appropriate `push` + branch triggers. + +```yml +name: docs-build + +on: + push: + branches: + - main + - '\d+.\d+' <1> + pull_request_target: ~ + merge_group: ~ + +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 +``` + +1. Ensure version branches are built and publish their links ahead of time. \ No newline at end of file From 3a5f1d572f585509a1a9d1cfd8eeb4ecf162e021 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Thu, 22 May 2025 13:03:46 +0200 Subject: [PATCH 2/4] update headings --- docs/migration/versioning.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/migration/versioning.md b/docs/migration/versioning.md index 489cf5a20..e3e7f4192 100644 --- a/docs/migration/versioning.md +++ b/docs/migration/versioning.md @@ -31,7 +31,7 @@ Our publish environments are connected to a single content source. This allows you as an owner of a repository to choose two different deployment models. -# Deployment models. +## Deployment models. The new documentation system supports 2 deployment models. @@ -43,7 +43,7 @@ Tagged deployment Allowing you to control the timing of when new documentation should go live. -## Continuous Deployment +### Continuous Deployment This is the default. To get started, follow our [guide](guide/index.md) to set up the new docs folder structure and CI configuration @@ -68,7 +68,7 @@ references: % TODO we need navigation.yml docs Once the repository is added, its navigation still needs to be injected into to global site navigation. -## Tagged Deployment +### Tagged Deployment If you want to have more control over the timing of when your docs go live to production. Configure the repository in our `assembler.yml` to have a fixed git reference (typically a branch) deploy the `current` content source to production. @@ -85,7 +85,7 @@ In order for `9.0` to be onboarded it needs to first follow our [migration guide Our CI integration checks will block until `current` is successfully configured ::: -### CI Configuration +#### CI Configuration To ensure [tagged deployments](#tagged-deployment) can be onboarded correctly, our CI integration needs to have appropriate `push` branch triggers. From e469d83fc9876d0b4934fdeceae280f3263d29c0 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Thu, 22 May 2025 13:07:13 +0200 Subject: [PATCH 3/4] update definition lists --- docs/migration/versioning.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/migration/versioning.md b/docs/migration/versioning.md index e3e7f4192..c3a1a7c46 100644 --- a/docs/migration/versioning.md +++ b/docs/migration/versioning.md @@ -15,10 +15,10 @@ For versioning plan details, check [Docs Versioning plan](https://docs.google.co To support multiple deployment models for different repositories, we support the concept of a content source. Next -: The source for the upcoming documentation. +: The source for the upcoming documentation. Current -: The source for the active documentation. +: The source for the active documentation. Our publish environments are connected to a single content source. @@ -36,11 +36,11 @@ This allows you as an owner of a repository to choose two different deployment m The new documentation system supports 2 deployment models. Continuous deployment. -: This is the default where a repositories `main` or `master` branch is continuously deployed to production. +: This is the default where a repositories `main` or `master` branch is continuously deployed to production. Tagged deployment -: Allows you to 'tag' a single git reference (typically a branch) as `current` which will be used to deploy to production. - Allowing you to control the timing of when new documentation should go live. +: Allows you to 'tag' a single git reference (typically a branch) as `current` which will be used to deploy to production. + Allowing you to control the timing of when new documentation should go live. ### Continuous Deployment From a0c50b79459c07b68c84fc761fa4da8c3b519e41 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Thu, 22 May 2025 13:10:52 +0200 Subject: [PATCH 4/4] fix header --- docs/migration/versioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration/versioning.md b/docs/migration/versioning.md index c3a1a7c46..46a40bfe6 100644 --- a/docs/migration/versioning.md +++ b/docs/migration/versioning.md @@ -10,7 +10,7 @@ To ensure a seamless experience for users and contributors, the new versioning a For versioning plan details, check [Docs Versioning plan](https://docs.google.com/presentation/d/1rHl0ia0ZkLHPLAYE5522CTDoatqwAxwAo29_etStPW8/edit?usp=sharing). To learn how to call out versioning differences in docs-builder, see [product availability](../syntax/applies.md). -# Content Sources +## Content Sources To support multiple deployment models for different repositories, we support the concept of a content source.