diff options
Diffstat (limited to 'doc/development/fe_guide/tooling.md')
| -rw-r--r-- | doc/development/fe_guide/tooling.md | 85 |
1 files changed, 60 insertions, 25 deletions
diff --git a/doc/development/fe_guide/tooling.md b/doc/development/fe_guide/tooling.md index 7a2d8fccdbf..c493ab9a206 100644 --- a/doc/development/fe_guide/tooling.md +++ b/doc/development/fe_guide/tooling.md @@ -17,7 +17,7 @@ This section describes yarn scripts that are available to validate and apply aut To check all staged files (based on `git diff`) with ESLint, run the following script: ```shell -yarn eslint-staged +yarn run lint:eslint:staged ``` A list of problems found are logged to the console. @@ -25,7 +25,7 @@ A list of problems found are logged to the console. To apply automatic ESLint fixes to all staged files (based on `git diff`), run the following script: ```shell -yarn eslint-staged-fix +yarn run lint:eslint:staged:fix ``` If manual changes are required, a list of changes are sent to the console. @@ -33,7 +33,7 @@ If manual changes are required, a list of changes are sent to the console. To check **all** files in the repository with ESLint, run the following script: ```shell -yarn eslint +yarn run lint:eslint ``` A list of problems found are logged to the console. @@ -41,7 +41,7 @@ A list of problems found are logged to the console. To apply automatic ESLint fixes to **all** files in the repository, run the following script: ```shell -yarn eslint-fix +yarn run lint:eslint:fix ``` If manual changes are required, a list of changes are sent to the console. @@ -98,6 +98,57 @@ When declaring multiple globals, always use one `/* global [name] */` line per v /* global jQuery */ ``` +### Deprecating functions with `import/no-deprecated` + +Our `@gitlab/eslint-plugin` Node module contains the [`eslint-plugin-import`](https://gitlab.com/gitlab-org/frontend/eslint-plugin) package. + +We can use the [`import/no-deprecated`](https://github.com/benmosher/eslint-plugin-import/blob/HEAD/docs/rules/no-deprecated.md) rule to deprecate functions using a JSDoc block with a `@deprecated` tag: + +```javascript +/** + * Convert search query into an object + * + * @param {String} query from "document.location.search" + * @param {Object} options + * @param {Boolean} options.gatherArrays - gather array values into an Array + * @returns {Object} + * + * ex: "?one=1&two=2" into {one: 1, two: 2} + * @deprecated Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information + */ +export function queryToObject(query, options = {}) { + ... +} +``` + +It is strongly encouraged that you: + +- Put in an **alternative path for developers** looking to use this function. +- **Provide a link to the issue** that tracks the migration process. + +NOTE: +Uses are detected if you import the deprecated function into another file. They are not detected when the function is used in the same file. + +Running `$ yarn eslint` after this will give us the list of deprecated usages: + +```shell +$ yarn eslint + +./app/assets/javascripts/issuable_form.js + 9:10 error Deprecated: Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information import/no-deprecated + 33:23 error Deprecated: Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information import/no-deprecated +... +``` + +Grep for disabled cases of this rule to generate a working list to create issues from, so you can track the effort of removing deprecated uses: + +```shell +$ grep "eslint-disable.*import/no-deprecated" -r . + +./app/assets/javascripts/issuable_form.js:import { queryToObject, objectToQuery } from './lib/utils/url_utility'; // eslint-disable-line import/no-deprecate +./app/assets/javascripts/issuable_form.js: // eslint-disable-next-line import/no-deprecated +``` + ## Formatting with Prettier > Support for `.graphql` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227280) in GitLab 13.2. @@ -125,44 +176,28 @@ Please take care that you only let Prettier format the same file types as the gl The following yarn scripts are available to do global formatting: ```shell -yarn prettier-staged-save +yarn run lint:prettier:staged:fix ``` Updates all staged files (based on `git diff`) with Prettier and saves the needed changes. ```shell -yarn prettier-staged +yarn run lint:prettier:staged ``` Checks all staged files (based on `git diff`) with Prettier and log which files would need manual updating to the console. ```shell -yarn prettier-all +yarn run lint:prettier ``` Checks all files with Prettier and logs which files need manual updating to the console. ```shell -yarn prettier-all-save -``` - -Formats all files in the repository with Prettier. (This should only be used to test global rule updates otherwise you would end up with huge MR's). - -The source of these Yarn scripts can be found in `/scripts/frontend/prettier.js`. - -#### Scripts during Conversion period - -```shell -node ./scripts/frontend/prettier.js check-all ./vendor/ -``` - -This iterates over all files in a specific folder, and checks them. - -```shell -node ./scripts/frontend/prettier.js save-all ./vendor/ +yarn run lint:prettier:fix ``` -This iterates over all files in a specific folder and saves them. +Formats all files in the repository with Prettier. ### VSCode Settings |