Commit 0e9d641a authored by Suzanne Selhorn's avatar Suzanne Selhorn

Merge branch 'docs-update-redirect-guidance' into 'master'

Update redirects guidance

See merge request gitlab-org/gitlab!81498
parents 642d61f7 bbc0a4e3
......@@ -6,4 +6,6 @@ remove_date: '2022-03-04'
This document was moved to [another location](check.md#verify-database-values-can-be-decrypted-using-the-current-secrets).
<!-- This redirect file can be deleted after 2022-03-04. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
......@@ -6,4 +6,6 @@ remove_date: '2022-04-06'
This document was moved to [another location](project_access_tokens.md).
<!-- This redirect file can be deleted after <2022-04-06>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
......@@ -6,4 +6,6 @@ remove_date: '2023-01-31'
This document was moved to [another location](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/11-0-stable/doc/api/v3_to_v4.md).
<!-- This redirect file can be deleted after <2023-01-31>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
......@@ -6,4 +6,6 @@ remove_date: '2022-04-27'
This document was moved to [another location](merged_results_pipelines.md).
<!-- This redirect file can be deleted after 2022-04-27. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
......@@ -27,7 +27,7 @@ Add a redirect to ensure:
- Users see the new page and can update or delete their bookmark.
- External sites can update their links, especially sites that have automation that
check for redirecting links.
checks for redirected links.
- The documentation site global navigation does not link to a missing page.
The links in the global navigation are already tested in the `gitlab-docs` project.
......@@ -38,26 +38,28 @@ Technical Writers can help with any questions and can review your change.
There are two types of redirects:
- Redirect added into the documentation files themselves, for users who
- [Redirect added into the documentation files themselves](#add-a-redirect), for users who
view the docs in `/help` on self-managed instances. For example,
[`/help` on GitLab.com](https://gitlab.com/help).
- [GitLab Pages redirects](../../user/project/pages/redirects.md),
for users who view the docs on [`docs.gitlab.com`](https://docs.gitlab.com).
[`/help` on GitLab.com](https://gitlab.com/help). These must be added in the same
MR that renames or moves a doc. Redirects to internal pages expire after three months
and redirects to external pages (starting with `https:`) expire after a year.
- [GitLab Pages redirects](../../user/project/pages/redirects.md), which are added
automatically after redirect files expire. They must not be manually added by
contributors and expire after nine months. Redirects pointing to external sites
are not added to the GitLab Pages redirects.
The Technical Writing team manages the [process](https://gitlab.com/gitlab-org/technical-writing/-/blob/main/.gitlab/issue_templates/tw-monthly-tasks.md)
to regularly update and [clean up the redirects](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/raketasks.md#clean-up-redirects).
If you're a contributor, you may add a new redirect, but you don't need to delete
the old ones. This process is automatic and handled by the Technical
Writing team.
Expired redirect files are removed from the documentation projects by the
[`clean_redirects` Rake task](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/raketasks.md#clean-up-redirects),
as part of the Technical Writing team's [monthly tasks](https://gitlab.com/gitlab-org/technical-writing/-/blob/main/.gitlab/issue_templates/tw-monthly-tasks.md).
## Add a redirect
NOTE:
If the old page you're renaming doesn't exist in a stable branch, skip the
following steps and ask a Technical Writer to add the redirect in
[`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml).
For example, if you add a new page on the 3rd of the month and then rename it before it gets
added in the stable branch on the 18th, the old page will never be part of the internal `/help`.
In that case, you can jump straight to the
[Pages redirect](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/maintenance.md#pages-redirects).
If the renamed page is new, you can sometimes skip the following steps and ask a
Technical Writer to manually add the redirect to [`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml).
For example, if you add a new page and then rename it before it's added to a release
on the 18th. The old page is not in any version's `/help` section, so a technical writer
can jump straight to the [Pages redirect](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/maintenance.md#pages-redirects).
To add a redirect:
......@@ -87,20 +89,13 @@ To add a redirect:
bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, https://example.com]"
```
Alternatively, you can omit the arguments and be asked to enter their values:
```shell
bundle exec rake gitlab:docs:redirect
```
If you don't want to use the Rake task, you can use the following template.
- Alternatively, you can omit the arguments and be prompted to enter the values:
Replace the value of `redirect_to` with the new file path and `YYYY-MM-DD`
with the date the file should be removed.
```shell
bundle exec rake gitlab:docs:redirect
```
Redirect files that link to docs in internal documentation projects
are removed after three months. Redirect files that link to external sites are
removed after one year:
If you don't want to use the Rake task, you can use the following template:
```markdown
---
......@@ -111,9 +106,14 @@ To add a redirect:
This document was moved to [another location](../path/to/file/index.md).
<!-- This redirect file can be deleted after <YYYY-MM-DD>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
```
- Replace both instances of `../newpath/to/file/index.md` with the new file path.
- Replace `YYYY-MM-DD` with the expiry date, as explained in the template.
1. If the documentation page being moved has any Disqus comments, follow the steps
described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments).
1. Open a merge request with your changes. If a documentation page
......
......@@ -6,4 +6,6 @@ remove_date: '2022-04-13'
This document was moved to [another location](gitlab_experiment.md).
<!-- This redirect file can be deleted after <2022-04-13>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
......@@ -6,4 +6,6 @@ remove_date: '2022-03-01'
This document was moved to [another location](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/).
<!-- This redirect file can be deleted after 2022-03-01. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
......@@ -6,4 +6,6 @@ remove_date: '2022-04-13'
This document was moved to [another location](sidekiq/index.md).
<!-- This redirect file can be deleted after <2022-04-13>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
......@@ -6,4 +6,6 @@ remove_date: '2022-03-08'
This document was removed. For information about installing GitLab, see [this page](../index.md).
<!-- This redirect file can be deleted after <2022-03-08>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
......@@ -6,4 +6,6 @@ remove_date: '2022-05-10'
This document was moved to [another location](../user/project/repository/push_rules.md).
<!-- This redirect file can be deleted after <2022-05-10>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
......@@ -6,4 +6,6 @@ remove_date: '2022-02-24'
This file was moved to [another location](index.md).
<!-- This redirect file can be deleted after <2022-02-24>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
......@@ -6,4 +6,6 @@ remove_date: '2022-03-14'
This file was moved to [another location](custom_domains_ssl_tls_certification/lets_encrypt_integration.md).
<!-- This redirect file can be deleted after <2022-03-14>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
......@@ -54,7 +54,9 @@ namespace :gitlab do
post.puts "This document was moved to [another location](#{new_path})."
post.puts
post.puts "<!-- This redirect file can be deleted after <#{date}>. -->"
post.puts "<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->"
post.puts "<!-- Redirects that point to other docs in the same project expire in three months. -->"
post.puts "<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. -->"
post.puts "<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->"
end
end
end
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment