﻿---
title: New versioning
description: As part of the new information architecture, pages with varying versioning schemes are now interwoven, creating the opportunity and necessity to rethink...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2652/migration/versioning
---

# New versioning
As part of the new information architecture, pages with varying versioning schemes are now interwoven, creating the opportunity and necessity to rethink the scope and versioning of each page. The previous approach of creating entirely separate docs sets for every minor version resulted in fragmentation and unnecessary duplication. Consolidating versioning resolves these issues while maintaining clarity and usability.
To ensure a seamless experience for users and contributors, the new versioning approach adheres to the following:
- **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. This is communicated using [`applies_to` tags](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2652/syntax/applies). 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.
- **Version awareness**: The documentation team tracks and maintains released versions for all products in a central configuration file.
- **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.

In this new system, documentation is written **cumulatively**. 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](https://www.elastic.co/docs/contribute-docs/how-to/cumulative-docs).

## Tag processing

`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.
The following table shows how badges for versioned products are displayed based on the release status for each lifecycle value. Hover over the example badges for the tooltip text.

| Lifecycle  | Release status | Badge text examples                                                   |
|------------|----------------|-----------------------------------------------------------------------|
| preview    | prerelease     | <applies-to>Elastic Stack: Planned</applies-to>                       |
|            | post-release   | <applies-to>Elastic Stack: Preview since 9.1</applies-to>             |
| beta       | prerelease     | <applies-to>Elastic Stack: Planned</applies-to>                       |
|            | post-release   | <applies-to>Elastic Stack: Beta since 9.1</applies-to>                |
| ga         | prerelease     | <applies-to>Elastic Stack: Planned</applies-to>                       |
|            | post-release   | <applies-to>Elastic Stack: Generally available since 9.1</applies-to> |
| deprecated | prerelease     | <applies-to>Elastic Stack: Planned for deprecation</applies-to>       |
|            | post-release   | <applies-to>Elastic Stack: Deprecated since 9.1</applies-to>          |
| removed    | prerelease     | <applies-to>Elastic Stack: Planned for removal</applies-to>           |
|            | post-release   | <applies-to>Elastic Stack: Removed in 9.1</applies-to>                |

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/config/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.
</note>


## Branching strategy

In Docs V3, a single branch is published per repository. This branch is set to `main` by default, but it is possible to instead publish a different branch by changing your repository's branching strategy. You might want to change your branching strategy so you can have more control over when content added for a specific release is published.
- [Learn how to choose the right branching strategy for your repository](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2652/contribute/branching-strategy)
- [Learn how to set up your selected branching strategy](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2652/configure/content-sources)