Add test for deleted or renamed docs
What does this MR do and why?
Adds a test to check for deleted/renamed documentation files without redirects.
If we accidentally remove/rename a doc page instead of redirecting it (keeping the old file), then there might be failures in the gitlab-docs
project in case the the renamed/deleted doc was present in the navbar. Examples:
Implements the following:
-
Fail when a doc is renamed without a proper redirect and the new name is not in the nav. If there are multiple files found, only the first is shown in the error message. -
Fail when a doc is deleted and the page is still in the nav. This can also happen when we clean up the redirects. In that case, the gitlab-docs
MR that adds the Pages redirects must be merged first. -
Provide a proper error message with links to documentation on how to fix the error. -
The task will fail on private MRs, for example, MRs on gitlab-org/security/gitlab
. Use a token to be able to use the API in those cases. Fixed with !126882 (c6e78a16).
Example failed job: https://gitlab.com/gitlab-org/gitlab/-/jobs/5058017441
Further improvements:
-
Include all found files if there are more than one. This can happen if we mass-rename files.
Related issues
How to set up and validate locally
-
Check out this branch or download the Ruby script.
-
Run the script against !131392 (closed) (check for deleted file):
CI_PROJECT_PATH='gitlab-org/gitlab' CI_MERGE_REQUEST_IID=131392 scripts/lint-docs-redirects.rb
-
You should see the following:
✖ ERROR: Missing redirect for a deleted or moved page The following file is linked in the global navigation for docs.gitlab.com: => doc/api/access_requests.md Unless you add a redirect or remove the page from the global navigation, this change will break pipelines in the 'gitlab/gitlab-docs' project. It seems you deleted a page. Run the following Rake task by replacing 'doc/new/path.md' with the page to redirect to, and commit the changes. bundle exec rake "gitlab:docs:redirect[doc/api/access_requests.md, doc/new/path.md]" For more information, see: - Create a redirect : https://docs.gitlab.com/ee/development/documentation/redirects.html - Edit the global nav : https://docs.gitlab.com/ee/development/documentation/site_architecture/global_nav.html#add-a-navigation-entry
-
Run the script against omnibus-gitlab!7136 (closed) (check for renamed file):
CI_PROJECT_PATH='gitlab-org/omnibus-gitlab' CI_MERGE_REQUEST_IID=7136 ./scripts/lint-docs-redirects.rb Checking renamed file... => Old_path: doc/settings/nginx.md => New_path: doc/settings/nginx_new.md ✖ ERROR: Missing redirect for a deleted or moved page The following file is linked in the global navigation for docs.gitlab.com: => doc/settings/nginx.md Unless you add a redirect or remove the page from the global navigation, this change will break pipelines in the 'gitlab/gitlab-docs' project. For more information, see: - Create a redirect : https://docs.gitlab.com/ee/development/documentation/redirects.html - Edit the global nav : https://docs.gitlab.com/ee/development/documentation/site_architecture/global_nav.html#add-a-navigation-entry
-
Run again the task without specifying an project ID and it should fail silently (it only runs with specific project IDs):
scripts/lint-docs-redirects.rb
-
Run again the task without specifying an MR ID and it should fail with an error message:
CI_PROJECT_PATH='gitlab-org/gitlab' scripts/lint-docs-redirects.rb
MR acceptance checklist
This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.
-
I have evaluated the MR acceptance checklist for this MR.