Skip to content

Add test for deleted or renamed docs

Achilleas Pipinellis - OOO until November 25th (parental leave) requested to merge axil-check-for-deleted-docs into master

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

  1. Check out this branch or download the Ruby script.

  2. 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

  3. 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

  4. 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

  5. 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

  6. 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.

Edited by Achilleas Pipinellis - OOO until November 25th (parental leave)

Merge request reports