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
Update versioning docs with deployment models and CI details (#1303)
* 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.
* update headings
* update definition lists
* fix header
Copy file name to clipboardExpand all lines: docs/migration/versioning.md
+107-1Lines changed: 107 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -7,4 +7,110 @@ To ensure a seamless experience for users and contributors, the new versioning a
7
7
* 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.
8
8
* 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.
9
9
10
-
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).
10
+
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).
11
+
12
+
13
+
## Content Sources
14
+
15
+
To support multiple deployment models for different repositories, we support the concept of a content source.
16
+
17
+
Next
18
+
: The source for the upcoming documentation.
19
+
20
+
Current
21
+
: The source for the active documentation.
22
+
23
+
24
+
Our publish environments are connected to a single content source.
25
+
26
+
| Publish Environment | Content Source |
27
+
|---------------------|----------------|
28
+
| Production |`Current`|
29
+
| Staging |`Current`|
30
+
| Edge |`Next`|
31
+
32
+
This allows you as an owner of a repository to choose two different deployment models.
33
+
34
+
## Deployment models.
35
+
36
+
The new documentation system supports 2 deployment models.
37
+
38
+
Continuous deployment.
39
+
: This is the default where a repositories `main` or `master` branch is continuously deployed to production.
40
+
41
+
Tagged deployment
42
+
: Allows you to 'tag' a single git reference (typically a branch) as `current` which will be used to deploy to production.
43
+
Allowing you to control the timing of when new documentation should go live.
44
+
45
+
46
+
### Continuous Deployment
47
+
48
+
This is the default. To get started, follow our [guide](guide/index.md) to set up the new docs folder structure and CI configuration
49
+
50
+
Once setup ensure the repository is added to our `assembler.yml` under `references`.
51
+
52
+
For example say you want to onboard `elastic/my-repository` into the production build:
53
+
54
+
```yaml
55
+
references:
56
+
my-repository:
57
+
```
58
+
59
+
Is equivalent to specifying.
60
+
61
+
```yaml
62
+
references:
63
+
my-repository:
64
+
next: main
65
+
current: main
66
+
```
67
+
68
+
% TODO we need navigation.yml docs
69
+
Once the repository is added, its navigation still needs to be injected into to global site navigation.
70
+
71
+
### Tagged Deployment
72
+
73
+
If you want to have more control over the timing of when your docs go live to production. Configure the repository
74
+
in our `assembler.yml` to have a fixed git reference (typically a branch) deploy the `current` content source to production.
75
+
76
+
```yaml
77
+
references:
78
+
my-other-repository:
79
+
next: main
80
+
current: 9.0
81
+
```
82
+
83
+
:::{note}
84
+
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.
85
+
Our CI integration checks will block until `current` is successfully configured
86
+
:::
87
+
88
+
#### CI Configuration
89
+
90
+
To ensure [tagged deployments](#tagged-deployment) can be onboarded correctly, our CI integration needs to have appropriate `push`
0 commit comments