You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/configure/content-sources.md
+8-8Lines changed: 8 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Content sources
2
2
3
-
To support multiple deployment models for different repositories, we support the concept of a content source.
3
+
To support multiple branching strategies for different repositories, we support the concept of a content source.
4
4
5
5
Next
6
6
: The source for the upcoming documentation.
@@ -17,16 +17,16 @@ Our publish environments are connected to a single content source.
17
17
| Staging |`Current`|
18
18
| Edge |`Next`|
19
19
20
-
This allows you as an owner of a repository to choose two different deployment models.
20
+
This allows you as an owner of a repository to choose two different branching strategies.
21
21
22
-
## Deployment models
22
+
## Branching strategies
23
23
24
-
The new documentation system supports 2 deployment models.
24
+
The new documentation system supports 2 branching strategies.
25
25
26
-
Continuous deployment.
26
+
Continuous deployment
27
27
: This is the default where a repositories `main` or `master` branch is continuously deployed to production.
28
28
29
-
Tagged deployment
29
+
Tagged
30
30
: Allows you to 'tag' a single git reference (typically a branch) as `current` which will be used to deploy to production.
31
31
Allowing you to control the timing of when new documentation should go live.
32
32
@@ -56,7 +56,7 @@ references:
56
56
% TODO we need navigation.yml docs
57
57
Once the repository is added, its navigation still needs to be injected into to global site navigation.
58
58
59
-
### Tagged deployment
59
+
### Tagged
60
60
61
61
If you want to have more control over the timing of when your docs go live to production. Configure the repository
62
62
in our `assembler.yml` to have a fixed git reference (typically a branch) deploy the `current` content source to production.
@@ -75,7 +75,7 @@ Our CI integration checks will block until `current` is successfully configured
75
75
76
76
#### CI configuration
77
77
78
-
To ensure [tagged deployments](#tagged-deployment) can be onboarded correctly, our CI integration needs to have appropriate `push`
78
+
To ensure repositories that use the [tagged branching strategy](#tagged) can be onboarded correctly, our CI integration needs to have appropriate `push`
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.
2
+
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.
3
3
4
-
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).
4
+
For detailed backporting guidance, refer to the example in [Choose the docs branching strategy for a repository](/contribute/branching-strategy.md#workflow-2-tagged-deployment).
5
5
6
6
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).
Copy file name to clipboardExpand all lines: docs/contribute/add-repo.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -55,7 +55,7 @@ references:
55
55
```
56
56
57
57
:::{tip}
58
-
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.
58
+
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.
59
59
:::
60
60
61
61
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.
Copy file name to clipboardExpand all lines: docs/contribute/branching-strategy.md
+32-23Lines changed: 32 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,12 @@
1
1
---
2
-
navigation_title: Choose a deployment model
2
+
navigation_title: Choose a branching strategy
3
3
---
4
4
5
-
# Choose the docs deployment model for a repository
5
+
# Choose the docs branching strategy for a repository
6
6
7
-
With Docs V3 (elastic.co/docs), a single branch is published per repository. This branch is set to `main` by default. This is known as the continuous deployment model. However, it is possible to instead publish a different branch, also known as the tagged deployment model.
7
+
With Docs V3 (elastic.co/docs), a single branch is published per repository. This branch is set to `main` by default. This is known as the continuous deployment branching strategy. However, it is possible to instead publish a different branch, also known as the tagged branching strategy.
8
8
9
-
On this page, you'll learn how to choose the right deployment model for your repository, and how to change the deployment model. You'll also learn about the workflows for working in each deployment model.
9
+
On this page, you'll learn how to choose the right branching strategy for your repository, and how to change the branching strategy. You'll also learn about the workflows for working with each branching strategy.
10
10
11
11
## Why is `main` the default publication branch?
12
12
@@ -25,38 +25,55 @@ Publishing from the main branch isn’t the best option for all repositories.
25
25
26
26
If you choose this publication model for your repository AND that repository includes {{serverless-short}} or {{ecloud}} documentation, you will need to make sure that {{serverless-short}}- and {{ecloud}}-related changes are also backported to the `current` branch in order to be published on time.
27
27
28
-
You **don't** need to change your deployment model to enable writing docs about future versions. Review the [continuous deployment workflow](#workflow-1-default-continuous-deployment) and [](cumulative-docs.md) to learn more.
28
+
You **don't** need to change your branching strategy to enable writing docs about future versions. Review the [continuous deployment workflow](#workflow-1-default-continuous-deployment) and [](cumulative-docs.md) to learn more.
29
29
30
30
Note that regardless of the publication branch that is set, the documentation must still flag all changes introduced so far since the last major release. This is NOT an alternative to [writing docs cumulatively](cumulative-docs.md).
31
31
32
32
## How to change the published branch
33
33
34
34
Choosing to switch between publishing docs from `main` and publishing docs from a version branch is a long-term decision. This decision impacts all docs for an entire repository. Reach out to the docs team to discuss the change.
35
35
36
+
For more information, refer to [](/configure/content-sources.md).
37
+
36
38
After it has been established that a repository should publish from a version branch rather than `main`:
37
39
38
-
1. In the [docs assembler file](https://github.com/elastic/docs-builder/blob/main/src/tooling/docs-assembler/assembler.yml):
40
+
1.[Add new triggers to the `docs-build` CI integration](/configure/content-sources.md#ci-configuration). Merge these changes to `main` or `master` and the intended version branches.
41
+
2. Open a PR to trigger the CI integration and confirm that the docs build.
42
+
3. Open a PR updating the [docs assembler file](https://github.com/elastic/docs-builder/blob/main/src/tooling/docs-assembler/assembler.yml):
39
43
* Specify which is the `current` branch for the repository. This branch is the branch from which docs are deployed to production at [elastic.co/docs](http://elastic.co/docs).
40
44
* Specify which is the `next` branch for the repository. The branch defined as `next` publishes docs internally to [staging-website.elastic.co/docs](http://staging-website.elastic.co/docs)
41
45
* Setting this branch to the next version branch in line is a good practice to preview docs change for an upcoming version.
42
46
* 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.
43
-
2.[Add new triggers to the `docs-build` CI integration](/configure/deployment-models.md#ci-configuration).
44
-
3. Add an action as part of that repo’s release process for the release manager to update this same assembler file and bump the `current` branch with each release, as appropriate. The `next` branch also needs to be bumped if it is not set to `main`.
45
-
4. When these releases happen, create a PR against the [assembler file](https://github.com/elastic/docs-builder/blob/main/src/tooling/docs-assembler/assembler.yml) that defines the new `current` branch, to merge on release day.
47
+
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:
5. Rerun the `validate-assembler` check on the PR.
53
+
6. After checks pass and the docs engineering team approves, you can merge the PR.
54
+
55
+
After these steps are completed, the docs engineering team needs to release a new version of our build tool to complete the process. This process will be decoupled in a future release. After a new version is released, the switch is complete and the production documentation reflects the specified current branch.
56
+
57
+
### Update the release process
58
+
59
+
When you publish from specific version branches, you need to bump the version branch as part of the release process.
60
+
61
+
Add an action as part of that repo’s release process for the release manager to update this same assembler file and bump the `current` branch with each release, as appropriate. The `next` branch also needs to be bumped if it is not set to `main`.
62
+
63
+
When these releases happen, create a PR against the [assembler file](https://github.com/elastic/docs-builder/blob/main/src/tooling/docs-assembler/assembler.yml) that defines the new `current` branch, to merge on release day.
46
64
47
-
For more information, refer to [](/configure/deployment-models.md).
48
65
49
66
## Workflow 1 (default): Continuous deployment
50
67
51
-
Learn how to make updates in the continuous deployment model, where the repo is publishing docs from `main`.
68
+
Learn how to make updates in the continuous deployment branching strategy, where the repo is publishing docs from `main`.
52
69
53
70
### Where to make docs changes [make-changes-cd]
54
71
55
72
Initiate the changes by opening a PR against the `main` branch of the repo.
56
73
57
74
### How to write those changes [write-changes-cd]
58
75
59
-
In our markdown-based documentation system, we [write docs cumulatively](cumulative-docs.md) regardless of the publication model selected.
76
+
In elastic.co/docs (Docs V3), we [write docs cumulatively](cumulative-docs.md) regardless of the branching strategy selected.
60
77
61
78
### Merging and backporting [merge-backport-cd]
62
79
@@ -74,21 +91,17 @@ When a repo is publishing docs from its `main` branch, no backporting is needed.
74
91
If you don’t want to hold on too many PRs to publish on release day, merge them to a feature branch, so you only have to merge this feature branch to `main` on release day.
75
92
:::
76
93
77
-
### More examples [more-examples-cd]
78
-
79
-
We’ve prepared a few end-to-end examples to help in [Figma](https://www.figma.com/design/CZDl0szuGsQfJhFpnwJVWS/Applies_to-Docs-V3?node-id=0-1&p=f&t=lBPrvde0k5zg9U0E-0).
80
-
81
-
## Workflow 2: Tagged deployment
94
+
## Workflow 2: Tagged
82
95
83
-
Learn how to make updates in the continuous deployment model, where the repo is publishing docs from a specific `version` branch.
96
+
Learn how to make updates in the continuous deployment branching strategy, where the repo is publishing docs from a specific `version` branch.
84
97
85
98
### Where to make docs changes [make-changes-td]
86
99
87
100
Initiate the changes by opening a PR against the `main` branch of the repo. The changes will be backported to the relevant version branches as detailed below.
88
101
89
102
### How to write those changes [write-changes-td]
90
103
91
-
In our markdown-based documentation system, we [write docs cumulatively](cumulative-docs.md) regardless of the publication model selected.
104
+
In elastic.co/docs (Docs V3), we [write docs cumulatively](cumulative-docs.md) regardless of the branching strategy selected.
92
105
93
106
### Merging and backporting [merge-backport-td]
94
107
@@ -117,7 +130,3 @@ For example, in a situation where 9.0, 9.1, and 9.2 are already released, and th
117
130
:::{note}
118
131
While you *can* backport to versions prior to the `current` version when applicable to maintain parity between the code and the docs on a given branch, that content will not be used in the current state of the docs.
119
132
:::
120
-
121
-
### More examples [more-examples-td]
122
-
123
-
We’ve prepared a few end-to-end examples to help in [Figma](https://www.figma.com/design/CZDl0szuGsQfJhFpnwJVWS/Applies_to-Docs-V3?node-id=0-1&p=f&t=lBPrvde0k5zg9U0E-0).
Copy file name to clipboardExpand all lines: docs/contribute/cumulative-docs.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
This page explains our cumulative documentation philosophy, paired with examples. Component guidance for reference purposes goes in syntax/applies.md.
5
5
-->
6
6
7
-
In our markdown-based documentation system, we write docs cumulatively regardless of the [deployment model](deployment-models.md) selected.
7
+
In elastic.co/docs (Docs V3), we write docs cumulatively regardless of the [branching strategy](branching-strategy.md) selected.
8
8
9
9
**What does this mean?**
10
10
@@ -109,7 +109,7 @@ For this case, no specific version tagging is necessary.
109
109
**A new feature is added to {{serverless-short}} or {{ecloud}}. How do I tag it?**
110
110
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.
111
111
112
-
However, in this scenario, it is important to consider carefully [when the change is going to be published](deployment-models.md).
112
+
However, in this scenario, it is important to consider carefully [when the change is going to be published](branching-strategy.md).
113
113
114
114
We do not do date-based tagging for unversioned products.
Copy file name to clipboardExpand all lines: docs/contribute/index.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,14 +15,6 @@ In April 2025, we released our new documentation site. This site includes docume
15
15
:::{include} _snippets/two-systems.md
16
16
:::
17
17
18
-
### Contribute to elastic.co/guide
19
-
20
-
:::{include} _snippets/guide-intro.md
21
-
:::
22
-
23
-
* For **simple bug fixes and enhancements**: [Contribute on the web](on-the-web.md)
24
-
* For **complex or multi-page updates**: See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation)
25
-
26
18
### Contribute elastic.co/docs
27
19
28
20
:::{include} _snippets/docs-intro.md
@@ -35,7 +27,15 @@ In April 2025, we released our new documentation site. This site includes docume
35
27
36
28
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 deployment model. You might want to change your deployment model so you can have more control over when content added for a specific release is published.
37
29
38
-
[Learn more about deployment models](deployment-models.md).
30
+
[Learn more about branching strategies](branching-strategy.md).
31
+
32
+
### Contribute to elastic.co/guide
33
+
34
+
:::{include} _snippets/guide-intro.md
35
+
:::
36
+
37
+
* For **simple bug fixes and enhancements**: [Contribute on the web](on-the-web.md)
38
+
* For **complex or multi-page updates**: See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation)
Copy file name to clipboardExpand all lines: docs/contribute/on-the-web.md
+14-14Lines changed: 14 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,38 +7,38 @@ This section will help you understand how to update and contribute to our docume
7
7
:::{include} _snippets/two-systems.md
8
8
:::
9
9
10
-
### Update elastic.co/guide [guide]
10
+
### Update elastic.co/docs (Docs V3) [docs]
11
11
12
-
:::{include} _snippets/guide-intro.md
12
+
:::{include} _snippets/docs-intro.md
13
13
:::
14
14
15
-
These changes should be made in the original source folders in their respective repositories. Here’s how you can do it:
15
+
For content hosted on elastic.co/docs, most conceptual and narrative content is stored in the [`docs-content`](https://github.com/elastic/docs-content) repository, and most reference content is hosted in the relevant product's repository. Follow these steps to ensure your contributions are correctly made:
16
16
17
17
1. Navigate to the page that is impacted.
18
18
2. Click the **Edit** button.
19
-
3.Ensure the targeted branch is \<insert proper branch\>.
19
+
3.Identify the section that requires updates.
20
20
4. Make the necessary updates.
21
-
5. Commit your changes and create a pull request.
22
-
6. Add the appropriate labels per repo as found at [Page: Working across docs repos](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/61604182/Working+across+docs+repos)
21
+
5. Commit your changes and create a pull request.
23
22
24
-
:::{note}
25
-
If you are working in a repo like Kibana or the cloud repo, backports can be complicated. You can use the [backport tool](https://github.com/sorenlouv/backport) to manage your backport.
23
+
:::{include} _snippets/tagged-warning.md
26
24
:::
27
25
28
-
### Update elastic.co/docs [docs]
26
+
### Update elastic.co/guide [guide]
29
27
30
-
:::{include} _snippets/docs-intro.md
28
+
:::{include} _snippets/guide-intro.md
31
29
:::
32
30
33
-
For content hosted on elastic.co/docs, most conceptual and narrative content is stored in the [`docs-content`](https://github.com/elastic/docs-content) repository, and most reference content is hosted in the relevant product's repository. Follow these steps to ensure your contributions are correctly made:
31
+
These changes should be made in the original source folders in their respective repositories. Here’s how you can do it:
34
32
35
33
1. Navigate to the page that is impacted.
36
34
2. Click the **Edit** button.
37
-
3.Identify the section that requires updates.
35
+
3.Ensure the targeted branch is \<insert proper branch\>.
38
36
4. Make the necessary updates.
39
-
5. Commit your changes and create a pull request.
37
+
5. Commit your changes and create a pull request.
38
+
6. Add the appropriate labels as required by the repo. To learn which labels to add, refer to the contribution documentation for that repo or reach out to the file codeowners.
40
39
41
-
:::{include} _snippets/tagged-warning.md
40
+
:::{note}
41
+
If you are working in a repo like Kibana or the cloud repo, backports can be complicated. You can use the [backport tool](https://github.com/sorenlouv/backport) to manage your backport.
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 deployment model. You might want to change your deployment model so you can have more control over when content added for a specific release is published.
20
+
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.
21
21
22
-
*[Learn how to choose the right deployment model for your repository](/contribute/deployment-models.md)
23
-
*[Learn how to set up your selected deployment model](/configure/deployment-models.md)
22
+
*[Learn how to choose the right branching strategy for your repository](/contribute/branching-strategy.md)
23
+
*[Learn how to set up your selected branching strategy](/configure/content-sources.md)
0 commit comments