Merge branch 'main' into fix/aws_cli_redirects

Author: cotti

.github/workflows/preview-build.yml

@@ -38,6 +38,11 @@ on:
         type: string
         default: '**'
         required: false
+      path-pattern-ignore:
+        description: 'Path pattern to ignore files.'
+        type: string
+        default: ''
+        required: false
       free-disk-space:
         description: 'Free disk space before running the build'
         type: string
@@ -118,6 +123,7 @@ jobs:
         uses: tj-actions/changed-files@2f7c5bfce28377bc069a65ba478de0a74aa0ca32 # v46.0.1
         with:
           files: ${{ inputs.path-pattern != '' && inputs.path-pattern || '**' }}
+          files_ignore: ${{ inputs.path-pattern-ignore != '' && inputs.path-pattern-ignore || '' }}
 
       - name: Checkout
         if: env.MATCH == 'true' && (startsWith(github.event_name, 'pull_request') && steps.check-files.outputs.any_modified == 'true')

docs/_docset.yml

@@ -13,6 +13,9 @@ subs:
   serverless-short: Serverless
   ece:   "Elastic Cloud Enterprise"
   eck:   "Elastic Cloud on Kubernetes"
+  ech:  "Elastic Cloud Hosted"
+  serverless-full: "Elastic Cloud Serverless"
+  ecloud: "Elastic Cloud"
 
 features:
   primary-nav: false
@@ -31,6 +34,8 @@ toc:
       - file: on-the-web.md
       - file: move.md
       - file: redirects.md
+      - file: cumulative-docs.md
+      - file: branching-strategy.md
       - file: add-repo.md
   - folder: migration
     children:
@@ -69,6 +74,7 @@ toc:
           - file: navigation.md
           - file: extensions.md
       - file: page.md
+      - file: content-sources.md
   - folder: syntax
     children:
       - file: index.md

docs/configure/content-sources.md

@@ -0,0 +1,104 @@
+# Content sources
+
+To support multiple branching strategies 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 branching strategies.
+
+## Branching strategies
+
+The new documentation system supports 2 branching strategies.
+
+Continuous deployment 
+:   This is the default where a repositories `main` or `master` branch is continuously deployed to production.
+
+Tagged
+:   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](/migration/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
+
+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](/migration/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 repositories that use the [tagged branching strategy](#tagged) 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: write
+```
+
+1. Ensure version branches are built and publish their links ahead of time.

docs/contribute/_snippets/docs-intro.md

@@ -0,0 +1,5 @@
+elastic.co/docs uses our new build system, also known as "Docs V3", which uses an extended version of markdown as its markup language. Refer to our [syntax guide](/syntax/index.md) to learn more.
+
+Docs for {{stack}} 9.x, {{ece}} 4.x, and {{eck}} 3.x can all be found on this site. All unversioned products, such as {{ech}} and {{serverless-full}}, are also documented on elastic.co/docs.
+
+This documentation is **cumulative**. This means that a new set of docs is not published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content. [Learn how to write cumulative documentation](/contribute/cumulative-docs.md).

docs/contribute/_snippets/guide-intro.md

@@ -0,0 +1,3 @@
+To contribute to elastic.co/guide, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses ASCIIDoc as its markup language.
+
+Docs for {{stack}} 8.x, {{ece}} 3.x, and {{eck}} 2.x can all be found on this site.

docs/contribute/_snippets/tag-processing.md

@@ -0,0 +1,21 @@
+`applies_to` tags are rendered as badges in the documentation output. They reproduce the "key + lifecycle status + version" indicated in the content sources.
+
+Specifically for versioned products, badges will display differently when the `applies_to` key specifies a product version that has not been released to our customers yet.
+
+* `Planned` (if the lifecycle is preview, beta, or ga)
+  
+  Example: {applies_to}`stack: ga 99.99`
+* `Deprecation planned` (if the lifecycle is deprecated)
+  
+  Example: {applies_to}`stack: deprecated 99.99`
+* `Removal planned` (if the lifecycle is removed) 
+
+  Example: {applies_to}`stack: removed 99.99`
+
+This is computed at build time (there is a docs build every 30 minutes). The documentation team tracks and maintains released versions for these products centrally in [versions.yml](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation.Configuration/versions.yml).
+
+When multiple lifecycle statuses and versions are specified in the sources, several badges are shown.
+
+:::{note}
+Visuals and wording in the output documentation are subject to changes and optimizations.
+:::

docs/contribute/_snippets/tagged-warning.md

@@ -0,0 +1,7 @@
+:::{warning}
+Some repositories use a [tagged branching strategy](/contribute/branching-strategy.md), which means that their docs are published from a branch that is not `main` or `master`. In these cases, documentation changes need to be made to `main` or `master`, and then backported to the relevant branches.
+
+For detailed backporting guidance, refer to the example in [Choose the docs branching strategy for a repository](/contribute/branching-strategy.md#workflow-2-tagged).
+
+To determine the published branches for a repository, find the repository in [assembler.yml](https://github.com/elastic/docs-builder/blob/main/src/tooling/docs-assembler/assembler.yml).
+:::

docs/contribute/_snippets/two-systems.md

@@ -0,0 +1,7 @@
+Because the new documentation site only hosts documentation for newer releases, the way that you contribute depends on the version that you want to document.
+
+For a list of versions covered on [elastic.co/docs](https://www.elastic.co/docs), refer to [Find docs for your product version](https://www.elastic.co/docs/get-started/versioning-availability#find-docs-for-your-product-version). Versions prior to the versions listed on that page are documented on our legacy system, [elastic.co/guide](https://www.elastic.co/guide). 
+
+:::{tip}
+Unversioned products, such as {{ech}} and {{serverless-full}}, are documented on [elastic.co/docs](https://www.elastic.co/docs).
+:::

docs/contribute/add-repo.md

@@ -54,6 +54,10 @@ references:
   yadda-docs:
 ```
 
+:::{tip}
+In this file, you can optionally specify custom branches to deploy docs from, depending on your preferred [branching strategy](branching-strategy.md). You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
+:::
+
 Then, edit the [navigation.yml](https://github.com/elastic/docs-builder/blob/main/src/tooling/docs-assembler/navigation.yml) file to add the repository to the navigation.
 
 For example, to add the `elastic/yadda-docs` repository under **Reference**: