1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
---
info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
stage: none
group: unassigned
description: 'Guidelines for deprecations and page removals'
---
# Deprecations and removals
When GitLab deprecates or removes a feature, use the following process to update the documentation.
This process requires temporarily changing content to be "deprecated" or "removed" before it's deleted.
If a feature is not generally available, you can delete the content outright instead of following these instructions.
NOTE:
A separate process exists for [GraphQL docs](../../api_graphql_styleguide.md#deprecating-schema-items)
and [REST API docs](../restful_api_styleguide.md#deprecations).
## Deprecate a page or topic
To deprecate a page or topic:
1. Add `(deprecated)` after the title. Use a warning to explain when it was deprecated,
when it will be removed, and the replacement feature.
```markdown
## Title (deprecated)
DETAILS:
**Tier:** Premium, Ultimate
**Offering:** GitLab.com, Self-managed, GitLab Dedicated
WARNING:
This feature was [deprecated](https://issue-link) in GitLab 14.8
and is planned for removal in 15.4. Use [feature X](link-to-docs.md) instead.
```
If you're not sure when the feature will be removed or no
replacement feature exists, you don't need to add this information.
1. If the deprecation is a [breaking change](../../../update/terminology.md#breaking-change), add this text:
```markdown
This change is a breaking change.
```
You can add any additional context-specific details that might help users.
1. Add the following HTML comments above and below the content. For `remove_date`,
set a date three months after the [release where it will be removed](https://about.gitlab.com/releases/).
```markdown
<!--- start_remove The following content will be removed on remove_date: 'YYYY-MM-DD' -->
## Title (deprecated)
DETAILS:
**Tier:** Premium, Ultimate
**Offering:** GitLab.com, Self-managed, GitLab Dedicated
WARNING:
This feature was [deprecated](https://issue-link) in GitLab 14.8
and is planned for removal in 15.4. Use [feature X](link-to-docs.md) instead.
<!--- end_remove -->
```
1. Open a merge request to add the word `(deprecated)` to the left nav, after the page title.
## Remove a page
Mark content as removed during the release the feature was removed.
The title and a removed indicator remains until three months after the removal.
To remove a page:
1. Leave the page title. Remove all other content, including the history items and the word `WARNING:`.
1. After the title, change `(deprecated)` to `(removed)`.
1. Update the YAML metadata:
- For `remove_date`, set the value to a date three months after
the release when the feature was removed.
- For the `redirect_to`, set a path to a file that makes sense. If no obvious
page exists, use the docs home page.
```markdown
---
stage: Data Stores
group: Global Search
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
remove_date: '2022-08-02'
redirect_to: '../newpath/to/file/index.md'
---
# Title (removed)
DETAILS:
**Tier:** Premium, Ultimate
**Offering:** GitLab.com, Self-managed, GitLab Dedicated
This feature was [deprecated](https://issue-link) in GitLab X.Y
and [removed](https://issue-link) in X.Y.
Use [feature X](link-to-docs.md) instead.
```
1. Edit the [`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml) in `gitlab-docs`
to remove the page's entry from the global navigation.
1. Search the [Deprecations and Removals](../../../update/deprecations.md) page for
links to the removed page. These are full URLs like: `https://docs.gitlab.com/ee/user/deprecated_page.html`.
If you find any links, update the relevant [YAML files](https://gitlab.com/gitlab-org/gitlab/-/tree/master/data/deprecations):
- In the `body:` section, remove links to the removed page.
- In the `documentation_url:` section, if the entry links to the page, delete the link.
- Run the Rake task to update the documentation:
```shell
bin/rake gitlab:docs:compile_deprecations
```
This content is removed from the documentation as part of the Technical Writing team's
[regularly scheduled tasks](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#regularly-scheduled-tasks).
## Remove a topic
To remove a topic:
1. Leave the title and the details of the deprecation and removal. Remove all other content,
including the history items and the word `WARNING:`.
1. Add `(removed)` after the title.
1. Add the following HTML comments above and below the topic.
For `remove_date`, set a date three months after the release where it was removed.
```markdown
<!--- start_remove The following content will be removed on remove_date: 'YYYY-MM-DD' -->
## Title (removed)
DETAILS:
**Tier:** Premium, Ultimate
**Offering:** GitLab.com, Self-managed, GitLab Dedicated
This feature was [deprecated](https://issue-link) in GitLab X.Y
and [removed](https://issue-link) in X.Y.
Use [feature X](link-to-docs.md) instead.
<!--- end_remove -->
```
1. Search the [Deprecations and Removals](../../../update/deprecations.md) page for
links to the removed page. These are full URLs like: `https://docs.gitlab.com/ee/user/deprecated_page.html`.
If you find any links, update the relevant [YAML files](https://gitlab.com/gitlab-org/gitlab/-/tree/master/data/deprecations):
- In the `body:` section, remove links to the removed page.
- In the `documentation_url:` section, if the entry links to the page, delete the link.
- Run the Rake task to update the documentation:
```shell
bin/rake gitlab:docs:compile_deprecations
```
This content is removed from the documentation as part of the Technical Writing team's
[regularly scheduled tasks](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#regularly-scheduled-tasks).
## Removing version-specific upgrade pages
Version-specific upgrade pages are in the `doc/update/versions/` directory.
We don't remove version-specific upgrade pages immediately for a major milestone. This gives
users time to upgrade from older versions.
For example, `doc/update/versions/14_changes.md` should
be removed during the `.3` milestone. Therefore `14_changes.md` are
removed in GitLab 17.3.
Instead of removing the unsupported page:
- [Add a note](#remove-a-topic) with a date three months
in the future to ensure the page is removed during the
[monthly maintenance task](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#regularly-scheduled-tasks).
- Do not add `Removed` to the title.
If the `X_changes.md` page contains relative links to other sections
that are removed as part of the versions cleanup, the `docs-lint links`
job might fail. You can replace those relative links with an [archived version](https://archives.docs.gitlab.com).
Choose the latest minor version of the unsupported version to be removed.
|
