Merge branch 'rfcs/80-mlunoe-add-and-document-process-for-using-import-no-deprecated' into 'master'

Feat(import/no-deprecated): add rule + docs

See merge request gitlab-org/gitlab!51991

app/assets/javascripts/diffs/store/utils.js

@@ -283,7 +283,7 @@ export function addContextLines(options) {
  * Trims the first char of the `richText` property when it's either a space or a diff symbol.
  * @param {Object} line
  * @returns {Object}
- * @deprecated
+ * @deprecated Use `line.rich_text = line.rich_text ? line.rich_text.replace(/^[+ -]/, '') : undefined;` instead!. For more information, see https://gitlab.com/gitlab-org/gitlab/-/issues/299329
  */
 export function trimFirstCharOfLineContent(line = {}) {
   // eslint-disable-next-line no-param-reassign

app/assets/javascripts/notes/stores/utils.js

-import { trimFirstCharOfLineContent } from '~/diffs/store/utils';
+import { trimFirstCharOfLineContent } from '~/diffs/store/utils'; // eslint-disable-line import/no-deprecated
 import createGqClient, { fetchPolicies } from '~/lib/graphql';
 import AjaxCache from '~/lib/utils/ajax_cache';
 import { sprintf, __ } from '~/locale';
@@ -34,7 +34,7 @@ export const hasQuickActions = (note) => createQuickActionsRegex().test(note);
 export const stripQuickActions = (note) => note.replace(createQuickActionsRegex(), '').trim();
 
 export const prepareDiffLines = (diffLines) =>
-  diffLines.map((line) => ({ ...trimFirstCharOfLineContent(line) }));
+  diffLines.map((line) => ({ ...trimFirstCharOfLineContent(line) })); // eslint-disable-line import/no-deprecated
 
 export const gqClient = createGqClient(
   {},

doc/development/fe_guide/tooling.md

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

package.json

@@ -164,7 +164,7 @@
   },
   "devDependencies": {
     "@babel/plugin-transform-modules-commonjs": "^7.10.1",
-    "@gitlab/eslint-plugin": "8.0.0",
+    "@gitlab/eslint-plugin": "8.1.0",
     "@gitlab/stylelint-config": "^2.2.0",
     "@testing-library/dom": "^7.16.2",
     "@vue/test-utils": "1.1.2",
@@ -177,17 +177,17 @@
     "commander": "^2.18.0",
     "custom-jquery-matchers": "^2.1.0",
     "docdash": "^1.0.2",
-    "eslint": "7.19.0",
+    "eslint": "7.20.0",
     "eslint-import-resolver-jest": "3.0.0",
     "eslint-import-resolver-webpack": "0.13.0",
     "eslint-plugin-jasmine": "4.1.2",
     "eslint-plugin-no-jquery": "2.5.0",
     "gettext-extractor": "^3.5.3",
     "gettext-extractor-vue": "^5.0.0",
+    "glob": "^7.1.6",
     "istanbul-lib-coverage": "^3.0.0",
     "istanbul-lib-report": "^3.0.0",
     "istanbul-reports": "^3.0.0",
-    "glob": "^7.1.6",
     "jasmine-core": "^2.9.0",
     "jasmine-diff": "^0.1.3",
     "jasmine-jquery": "^2.1.1",

spec/frontend/diffs/store/utils_spec.js

@@ -275,24 +275,28 @@ describe('DiffsStoreUtils', () => {
 
   describe('trimFirstCharOfLineContent', () => {
     it('trims the line when it starts with a space', () => {
+      // eslint-disable-next-line import/no-deprecated
       expect(utils.trimFirstCharOfLineContent({ rich_text: ' diff' })).toEqual({
         rich_text: 'diff',
       });
     });
 
     it('trims the line when it starts with a +', () => {
+      // eslint-disable-next-line import/no-deprecated
       expect(utils.trimFirstCharOfLineContent({ rich_text: '+diff' })).toEqual({
         rich_text: 'diff',
       });
     });
 
     it('trims the line when it starts with a -', () => {
+      // eslint-disable-next-line import/no-deprecated
       expect(utils.trimFirstCharOfLineContent({ rich_text: '-diff' })).toEqual({
         rich_text: 'diff',
       });
     });
 
     it('does not trims the line when it starts with a letter', () => {
+      // eslint-disable-next-line import/no-deprecated
       expect(utils.trimFirstCharOfLineContent({ rich_text: 'diff' })).toEqual({
         rich_text: 'diff',
       });
@@ -303,12 +307,14 @@ describe('DiffsStoreUtils', () => {
         rich_text: ' diff',
       };
 
+      // eslint-disable-next-line import/no-deprecated
       utils.trimFirstCharOfLineContent(lineObj);
 
       expect(lineObj).toEqual({ rich_text: ' diff' });
     });
 
     it('handles a undefined or null parameter', () => {
+      // eslint-disable-next-line import/no-deprecated
       expect(utils.trimFirstCharOfLineContent()).toEqual({});
     });
   });

yarn.lock

@@ -2,6 +2,13 @@
 # yarn lockfile v1
 
 
+"@babel/code-frame@7.12.11":
+  version "7.12.11"
+  resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.12.11.tgz#f4ad435aa263db935b8f10f2c552d23fb716a63f"
+  integrity sha512-Zt1yodBx1UcyiePMSkWnU4hPqhwq7hGi2nFL1LeA3EUl+q2LQx16MISgJ0+z7dnmgvP9QtIleuETGOiOH1RcIw==
+  dependencies:
+    "@babel/highlight" "^7.10.4"
+
 "@babel/code-frame@^7.0.0", "@babel/code-frame@^7.10.4", "@babel/code-frame@^7.12.13":
   version "7.12.13"
   resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.12.13.tgz#dcfc826beef65e75c50e21d3837d7d95798dd658"
@@ -242,7 +249,7 @@
     "@babel/traverse" "^7.12.13"
     "@babel/types" "^7.12.13"
 
-"@babel/highlight@^7.12.13":
+"@babel/highlight@^7.10.4", "@babel/highlight@^7.12.13":
   version "7.12.13"
   resolved "https://registry.yarnpkg.com/@babel/highlight/-/highlight-7.12.13.tgz#8ab538393e00370b26271b01fa08f7f27f2e795c"
   integrity sha512-kocDQvIbgMKlWxXe9fof3TQ+gkIPOUSEYhJjqUjvKMez3krV7vbzYCDq39Oj11UAVK7JqPVGQPlgE85dPNlQww==
@@ -861,10 +868,10 @@
   resolved "https://registry.yarnpkg.com/@gitlab/at.js/-/at.js-1.5.7.tgz#1ee6f838cc4410a1d797770934df91d90df8179e"
   integrity sha512-c6ySRK/Ma7lxwpIVbSAF3P+xiTLrNTGTLRx4/pHK111AdFxwgUwrYF6aVZFXvmG65jHOJHoa0eQQ21RW6rm0Rg==
 
-"@gitlab/eslint-plugin@8.0.0":
-  version "8.0.0"
-  resolved "https://registry.yarnpkg.com/@gitlab/eslint-plugin/-/eslint-plugin-8.0.0.tgz#e8d30fd98e2102f417617d0c60ef1810520a8ac6"
-  integrity sha512-hTTdcyxN3Ead2FaNwaiPg9sv2YbCDrlyAgKAPV7dit2uPqR0nkIlng9JPNMIixTXBrJ/Y+VvjIRrKKNYBubocw==
+"@gitlab/eslint-plugin@8.1.0":
+  version "8.1.0"
+  resolved "https://registry.yarnpkg.com/@gitlab/eslint-plugin/-/eslint-plugin-8.1.0.tgz#a98ac4219da3316d30ee717ef0603c8fa0c4d5d8"
+  integrity sha512-PU2ldrF59dhunMcEMzSqwG9RfTZRPmW8/pXwcXhJNi61g9lkdHQn8CiQGazepDlBwjEHl5habv/cs52gUc06+w==
   dependencies:
     babel-eslint "^10.0.3"
     eslint-config-airbnb-base "^14.2.1"
@@ -4732,12 +4739,12 @@ eslint-visitor-keys@^2.0.0:
   resolved "https://registry.yarnpkg.com/eslint-visitor-keys/-/eslint-visitor-keys-2.0.0.tgz#21fdc8fbcd9c795cc0321f0563702095751511a8"
   integrity sha512-QudtT6av5WXels9WjIM7qz1XD1cWGvX4gGXvp/zBn9nXG02D0utdU3Em2m/QjTnrsk6bBjmCygl3rmj118msQQ==
 
-eslint@7.19.0:
-  version "7.19.0"
-  resolved "https://registry.yarnpkg.com/eslint/-/eslint-7.19.0.tgz#6719621b196b5fad72e43387981314e5d0dc3f41"
-  integrity sha512-CGlMgJY56JZ9ZSYhJuhow61lMPPjUzWmChFya71Z/jilVos7mR/jPgaEfVGgMBY5DshbKdG8Ezb8FDCHcoMEMg==
+eslint@7.20.0:
+  version "7.20.0"
+  resolved "https://registry.yarnpkg.com/eslint/-/eslint-7.20.0.tgz#db07c4ca4eda2e2316e7aa57ac7fc91ec550bdc7"
+  integrity sha512-qGi0CTcOGP2OtCQBgWZlQjcTuP0XkIpYFj25XtRTQSHC+umNnp7UMshr2G8SLsRFYDdAPFeHOsiteadmMH02Yw==
   dependencies:
-    "@babel/code-frame" "^7.0.0"
+    "@babel/code-frame" "7.12.11"
     "@eslint/eslintrc" "^0.3.0"
     ajv "^6.10.0"
     chalk "^4.0.0"
@@ -4749,7 +4756,7 @@ eslint@7.19.0:
     eslint-utils "^2.1.0"
     eslint-visitor-keys "^2.0.0"
     espree "^7.3.1"
-    esquery "^1.2.0"
+    esquery "^1.4.0"
     esutils "^2.0.2"
     file-entry-cache "^6.0.0"
     functional-red-black-tree "^1.0.1"
@@ -4798,10 +4805,10 @@ esprima@^4.0.0, esprima@^4.0.1:
   resolved "https://registry.yarnpkg.com/esprima/-/esprima-4.0.1.tgz#13b04cdb3e6c5d19df91ab6987a8695619b0aa71"
   integrity sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==
 
-esquery@^1.0.1, esquery@^1.2.0:
-  version "1.3.1"
-  resolved "https://registry.yarnpkg.com/esquery/-/esquery-1.3.1.tgz#b78b5828aa8e214e29fb74c4d5b752e1c033da57"
-  integrity sha512-olpvt9QG0vniUBZspVRN6lwB7hOZoTRtT+jzR+tS4ffYx2mzbw+z0XCOk44aaLYKApNX5nMm+E+P6o25ip/DHQ==
+esquery@^1.0.1, esquery@^1.4.0:
+  version "1.4.0"
+  resolved "https://registry.yarnpkg.com/esquery/-/esquery-1.4.0.tgz#2148ffc38b82e8c7057dfed48425b3e61f0f24a5"
+  integrity sha512-cCDispWt5vHHtwMY2YrAQ4ibFkAL8RbH5YGBnZBc90MolvvfkkQcJro/aZiAQUlQ3qgrYS6D6v8Gc5G5CQsc9w==
   dependencies:
     estraverse "^5.1.0"