Skip to content

Lint against outdated usages of `helpPagePath`

Paul Gascou-Vaillancourt requested to merge help-page-path-exists into master

What does this MR do and why?

As docs pages get moved around or deleted, docs links that we display in the product might become outdated without us noticing. This adds an ESLint rule that ensures helpPagePath always points to files and anchors that still exist. In future iterations, we should add a similar rule to check usages of the HelpPageLink Vue component, and a Rubocop rule for the backend help_page_path helper.

What the rule checks exactly:

  • Whether the helper's first argument is passed as a string. Passing it as a variable isn't exactly a problem, but it does however make it harder to lint against improper usages of the linter. When wanting to store a help page path in a constant, it would be preferable to store helpPagePath's return value rather than its arguments.
  • Whether the provided path does correspond to an existing Markdown documentation file.
  • Whether the anchor–which can either be provided in the path argument, or in the second argument via the anchor property–exists in the Markdown file.

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

How to set up and validate locally

  1. Break a helpPagePath usage in a frontend file, then run ESLint against.

    • For example:

      diff --git a/app/assets/javascripts/authentication/webauthn/constants.js b/app/assets/javascripts/authentication/webauthn/constants.js
      index c41e6d2bd587..1b90f17f6fa8 100644
      --- a/app/assets/javascripts/authentication/webauthn/constants.js
      +++ b/app/assets/javascripts/authentication/webauthn/constants.js
      @@ -41,6 +41,6 @@ export const STATE_WAITING = 'waiting';
       export const WEBAUTHN_AUTHENTICATE = 'authenticate';
       export const WEBAUTHN_REGISTER = 'register';
       export const WEBAUTHN_DOCUMENTATION_PATH = helpPagePath(
      -  'user/profile/account/two_factor_authentication',
      +  'user/profile/account/two_factor_authentication/does/not/exist',
         { anchor: 'set-up-a-webauthn-device' },
       );
    • Then run yarn eslint app/assets/javascripts/authentication/webauthn/constants.js

  2. OR, lint all frontend files, assuming there are some violations, and they are not ignored:

    yarn lint:eslint:all
Edited by Paul Gascou-Vaillancourt

Merge request reports

Loading