Branching strategy selection, cumulative authoring, ++

docs/_docset.yml

@@ -1,4 +1,4 @@
 project: 'doc-builder'
 max_toc_depth: 2
 # indicates this documentation set is not linkable by assembler.
 # relaxes a few restrictions around toc building and file placement
@@ -13,6 +13,9 @@
   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 @@
       - file: on-the-web.md
       - file: move.md
       - file: redirects.md
+      - file: cumulative-docs.md
+      - file: deployment-models.md
       - file: add-repo.md
   - folder: migration
     children:
@@ -69,6 +74,7 @@
           - file: navigation.md
           - file: extensions.md
       - file: page.md
+      - file: deployment-models.md
   - folder: syntax
     children:
       - file: index.md

docs/configure/deployment-models.md

@@ -0,0 +1,104 @@
+# 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](/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 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](/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 [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: 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,17 @@
+`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)
+* `Deprecation planned` (if the lifecycle is deprecated)
+* `Removal planned` (if the lifecycle is removed) 
+
+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.
+
+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.
+:::
+
+% todo: link to central config

docs/contribute/_snippets/tagged-warning.md

@@ -0,0 +1,7 @@
+:::{warning}
+Some repositories use a [tagged deployment model](/contribute/deployment-models.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 deployment model for a repository](/contribute/deployment-models.md#workflow-2-tagged-deployment).
+
+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 [deployment model](deployment-models.md). You might want to change your deployment model 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**:

docs/contribute/cumulative-docs.md

@@ -0,0 +1,134 @@
+# Write cumulative documentation 
+
+<!--
+This page explains our cumulative documentation philosophy, paired with examples. Component guidance for reference purposes goes in syntax/applies.md. 
+-->
+
+In our markdown-based documentation system, we write docs cumulatively regardless of the [deployment model](deployment-models.md) selected.
+
+**What does this mean?** 
+
+With our markdown-based docs, there is no longer a new documentation set published with every minor release: the same page stays valid over time and shows version-related evolutions.
+
+This new behavior starts with the following **versions** of our products: Elastic Stack 9.0, ECE 4.0, ECK 3.0, and even more like EDOT docs. It also includes our unversioned products: Serverless and Elastic Cloud.
+
+:::{note} 
+Nothing changes for our ASCIIDoc-based documentation system, that remains published and maintained for the following versions: Elastic Stack until 8.19, ECE until 3.8, ECK until 2.x, etc.
+:::
+
+**How does it change the way we write docs?** 
+
+As new minor versions are released, we want users to be able to distinguish which content applies to their own ecosystem and product versions without having to switch between different versions of a page.
+
+This extends to deprecations and deletions: No information should be removed for supported product versions, unless it was never accurate. It can be refactored to improve clarity and flow, or to accommodate information for additional products, deployment types, and versions as needed.
+
+In order to achieve this, the markdown source files integrate a tagging system meant to identify:
+
+* [Which Elastic products and deployment models the content applies to](#tagging-products-and-deployment-models).  
+* [When a feature goes into a new state as compared to the established base version](#tagging-version-related-changes-mandatory).
+
+This tagging system is mandatory for all of the public-facing documentation. We refer to it as “[applies_to](https://elastic.github.io/docs-builder/syntax/applies/)” tags or badges.
+
+## Tagging products and deployment models
+
+### Page-level frontmatter (mandatory)
+
+All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use YAML frontmatter to indicate each deployment target's availability and lifecycle status. 
+
+* The `applies_to` attribute is used to display contextual badges on each page.  
+* The `products` attribute is used by the search to let users filter their results when searching the docs.
+
+  For the full list of supported keys and values, refer to [frontmatter](https://elastic.github.io/docs-builder/syntax/frontmatter).  
+
+
+:::{include} /syntax/_snippets/page-level-applies-examples.md
+:::
+
+### Section or inline contexts (situational)
+
+When the context differs from what was specified at the page level in a specific section or part of the page, it is appropriate to re-establish it. For example: 
+
+:::{include} /syntax/_snippets/section-level-applies-examples.md
+:::
+
+* Likewise, when the difference is specific to just one paragraph or list item, the same rules apply. Just the syntax slightly differs so that it stays inline:
+
+  :::{include} /syntax/_snippets/line-level-applies-example.md
+  :::
+
+### When should I indicate that something is NOT applicable to a specific context?
+
+By default, we communicate that content does not apply to a certain context by simply **not specifying it**.  
+For example, a page describing how to create an {{ech}} deployment just requires identifying "{{ech}}" as context. No need to overload the context with additional `serverless: unavailable` indicators.
+
+This is true for most situations. However, it can still be useful to call it out in a few specific scenarios:
+
+* When there is a high risk of confusion for users. This may be subjective, but let’s imagine a scenario where a feature is available in 2 out of 3 serverless project types. It may make sense to clarify and be explicit about the feature being “unavailable” for the 3rd type. For example: 
+
+  ```yml
+  --- 
+  applies_to:
+    stack: ga
+    serverless:
+      elasticsearch: ga
+      security: ga
+      observability: unavailable
+  ---
+  ```
+
+
+* When a specific section, paragraph or list item has specific applicability that differs from the context set at the page or section level, and the action is not possible at all for that context (meaning that there is no alternative). For example: 
+
+  ````md
+  --- 
+  applies_to:
+    stack: ga
+    serverless: ga
+  —--
+
+  # Spaces
+
+  [...]
+
+  ## Configure a space-level landing page [space-landing-page]
+  ```{applies_to}
+  stack: ga
+  serverless: unavailable
+  ```
+  ````
+% I think we wanted to not specify stack here
+
+## Tagging version-related changes (mandatory)
+
+In the previous section, we’ve considered product and deployment availability. Feature lifecycle and version-related changes are communicated as part of the same [applies\_to](https://elastic.github.io/docs-builder/syntax/applies/) tagging logic, by specifying different values to each supported key. 
+
+**Are you sure your change is related to a specific version? Maybe not…**  
+This is a frequent case. For example: fixing typos, improving styling, adding a long-forgotten setting, etc.  
+For this case, no specific version tagging is necessary.
+
+**A new feature is added to {{serverless-short}} or {{ecloud}}. How do I tag it?**  
+Cumulative documentation is not meant to replace release notes. If a feature becomes available in {{serverless-short}} and doesn’t have a particular lifecycle state to call out (preview, beta, deprecated…), it does not need specific tagging.
+
+However, in this scenario, it is important to consider carefully [when the change is going to be published](deployment-models.md).
+
+We do not do date-based tagging for unversioned products.
+
+### For unversioned products (typically {{serverless-short}} and {{ech}})
+
+:::{include} /syntax/_snippets/unversioned-lifecycle.md
+:::
+
+### For versioned products
+
+:::{include} /syntax/_snippets/versioned-lifecycle.md
+:::    
+
+### Identify multiple states for the same content  
+
+:::{include} /syntax/_snippets/multiple-lifecycle-states.md
+:::
+
+## How do these tags behave in the output? 
+
+:::{include} /contribute/_snippets/tag-processing.md
+:::