ESLint#

ESLint를 사용하여 프론트엔드 코드 표준을 캡슐화하고 적용합니다. 구성은 gitlab-eslint-config 프로젝트에서 확인할 수 있습니다.

환경 변수 REVEAL_ESLINT_TODO를 환경(및 IDE)에서 1로 설정하면 .eslint_todo/*.mjs에서 제외된 보류 중인 eslint todo 항목을 확인할 수 있습니다. 이를 통해 기존의 eslint 예외 항목을 드러내어 일상 작업 중에 수정할 수 있습니다.

Yarn 스크립트#

이 섹션에서는 ESLint를 사용하여 파일을 검증하고 자동 수정을 적용하는 데 사용할 수 있는 yarn 스크립트를 설명합니다.

ESLint로 스테이지된 모든 파일(git diff 기반)을 검사하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:staged

발견된 문제 목록이 콘솔에 출력됩니다.

ESLint 자동 수정을 스테이지된 모든 파일(git diff 기반)에 적용하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:staged:fix

수동 변경이 필요한 경우 변경 사항 목록이 콘솔에 출력됩니다.

리포지터리에서 특정 파일을 ESLint로 검사하려면 다음 스크립트를 실행합니다($PATH_TO_FILE를 실제 경로로 교체):

yarn run lint:eslint $PATH_TO_FILE

리포지터리의 모든 파일을 ESLint로 검사하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:all

발견된 문제 목록이 콘솔에 출력됩니다.

ESLint 자동 수정을 리포지터리의 모든 파일에 적용하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:all:fix

수동 변경이 필요한 경우 변경 사항 목록이 콘솔에 출력됩니다.

전역 규칙 업데이트에만 사용하세요. 그렇지 않으면 변경 사항으로 인해 대규모 머지 리퀘스트가 발생할 수 있습니다.

새 파일에서 ESLint 비활성화#

새 파일을 생성할 때 ESLint를 비활성화하지 마세요. 기존 파일에는 레거시 호환성 이유로 기존 규칙이 비활성화되어 있을 수 있지만, 현재 리팩토링 중입니다.

특정 ESLint 규칙을 비활성화하지 마세요. 기술 부채 발생을 방지하기 위해, 기존 코드 모듈을 호출/인스턴스화하는 경우에만 다음 규칙을 비활성화할 수 있습니다.

• no-new

• class-method-use-this

이러한 규칙은 줄 단위로 비활성화하세요. 그러면 향후 리팩토링이 더 쉬워집니다. 예를 들어 eslint-disable-next-line 또는 eslint-disable-line을 사용하세요.

단일 위반에 대해 ESLint 비활성화#

단일 위반에 대해 규칙을 비활성화해야 하는 경우, 필요한 최소한의 코드 범위에서만 비활성화하세요:

// bad
/* eslint-disable no-new */

import Foo from 'foo';

new Foo();

// better
import Foo from 'foo';

// eslint-disable-next-line no-new
new Foo();

todo 파일 생성#

코드베이스 전체에서 많은 위반을 발견하는 새 ESLint 규칙을 활성화할 때, 그러한 위반을 일시적으로 무시하기 위해 todo 파일을 생성하는 것이 더 쉬울 수 있습니다. 이 접근 방식에는 장단점이 있습니다:

장점:

• 특정 규칙을 위반하는 모든 파일에 대한 단일 진실 공급원(Single Source Of Truth, SSOT). 이를 통해 발생한 기술 부채를 해결하기 위한 작업을 더 쉽게 추적할 수 있습니다.

• 규칙을 처음 활성화할 때 위반하는 모든 파일을 수정할 필요가 없으므로 변경 집합이 더 작아집니다.

단점:

• 전체 파일에 대해 규칙을 비활성화하면 해당 파일에 동일한 유형의 위반이 더 많이 도입될 수 있습니다.

• 여러 동시 머지 리퀘스트에서 위반을 수정할 때 todo 파일에서 충돌이 자주 발생하여 MR 작성자가 브랜치를 리베이스해야 합니다.

todo 파일을 생성하려면 scripts/frontend/generate_eslint_todo_list.mjs 스크립트를 실행합니다:

node scripts/frontend/generate_eslint_todo_list.mjs <rule_name>

예를 들어, vue/no-unused-properties 규칙에 대한 todo 파일 생성:

node scripts/frontend/generate_eslint_todo_list.mjs vue/no-unused-properties

이렇게 하면 .eslint_todo/vue-no-unused-properties.mjs에 ESLint 구성이 생성되어 전역 구성에 자동으로 추가됩니다.

주어진 규칙에 대한 todo 파일이 생성되면, 해당 위반을 해결하기 위한 작업을 계획해야 합니다. todo 파일은 가능한 한 단기간에 처리되어야 합니다. 일부 위반을 해결할 수 없는 경우 단일 위반에 대해 ESLint 비활성화를 사용하여 인라인 무시로 전환하세요.

모든 위반 파일이 수정되면 todo 파일과 .eslint_todo/index.mjs의 export 구문을 함께 제거해야 합니다.

no-undef 규칙과 전역 변수 선언#

no-undef 규칙을 절대 비활성화하지 마세요. 대신 /* global Foo */로 전역 변수를 선언하세요.

여러 전역 변수를 선언할 때는 항상 변수마다 하나씩 /* global [name] */ 줄을 사용하세요.

// bad
/* globals Flash, Cookies, jQuery */

// good
/* global Flash */
/* global Cookies */
/* global jQuery */

import/no-deprecated를 사용하여 함수 사용 중단#

@gitlab/eslint-plugin Node 모듈에는 eslint-plugin-import 패키지가 포함되어 있습니다.

import/no-deprecated 규칙을 사용하여 @deprecated 태그가 있는 JSDoc 블록으로 함수를 사용 중단(deprecated)으로 표시할 수 있습니다:

/**
 * 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}
 *
 *For example: "?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 = {}) {
  ...
}

다음을 강력히 권장합니다:

• 이 함수를 사용하려는 개발자를 위한 대안 경로를 제공하세요.

• 마이그레이션 프로세스를 추적하는 이슈 링크를 제공하세요.

사용 중단된 함수를 다른 파일로 임포트하면 사용이 탐지됩니다. 같은 파일 내에서 함수를 사용할 경우에는 탐지되지 않습니다.

이후 $ yarn eslint를 실행하면 사용 중단된 사용 목록을 확인할 수 있습니다:

$ 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하여 작업 목록을 생성함으로써 사용 중단된 사용을 제거하는 노력을 추적하는 이슈를 만드세요:

$ 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

내 파일에서 vue/multi-word-component-names가 비활성화됨#

단일 이름 컴포넌트는 Vue 스타일 가이드에서 권장하지 않습니다.

단일 이름 컴포넌트는 다른 HTML 컴포넌트와 혼동될 수 있어 문제가 됩니다. 예를 들어 컴포넌트를 <table>로 이름 지으면 HTML <table> 렌더링이 중단됩니다.

이를 해결하기 위해 .vue 파일과 해당 참조를 두 단어 이상을 사용하여 이름을 바꾸어야 합니다. 예를 들면:

• user/table.vue는 user/users_table.vue로 이름을 바꾸고 UsersTable로 임포트하여 <users-table />로 사용할 수 있습니다.

GraphQL 스키마 및 오퍼레이션 유효성 검사#

@graphql-eslint/eslint-plugin을 사용하여 GraphQL 스키마와 오퍼레이션을 린트합니다. 이 플러그인이 제대로 작동하려면 전체 스키마가 필요합니다. 따라서 ESLint를 로컬에서 실행할 때 최신 스키마 덤프를 생성하는 것이 권장됩니다. ./scripts/dump_graphql_schema 스크립트를 실행하여 이를 수행할 수 있습니다.

Prettier로 포맷팅#

코드는 스타일 가이드를 따르기 위해 Prettier로 자동 포맷팅됩니다. Prettier는 표준 prettier 규칙에 따라 .js, .vue, .graphql, .scss 파일의 포맷팅을 처리합니다. Prettier의 모든 설정은 .prettierrc에서 확인할 수 있습니다.

에디터#

워크플로에 Prettier를 포함하는 권장 방법은 선호하는 에디터(모든 주요 에디터 지원)를 그에 맞게 설정하는 것입니다. 파일이 저장될 때마다 Prettier가 실행되도록 설정하는 것을 권장합니다. 선호하는 에디터에서 Prettier를 사용하는 방법은 Prettier 문서를 참조하세요.

전역 Yarn 스크립트와 동일한 파일 형식(.js, .vue, .graphql, .scss)만 Prettier로 포맷팅하도록 주의하세요. 예를 들어 Visual Studio Code 설정 파일에서 파일 형식을 제외할 수 있습니다:

  "prettier.disableLanguages": [
      "json",
      "markdown"
  ]

Yarn 스크립트#

전역 포맷팅을 위해 다음 yarn 스크립트를 사용할 수 있습니다:

yarn run lint:prettier:staged:fix

Prettier로 스테이지된 모든 파일(git diff 기반)을 업데이트하고 필요한 변경 사항을 저장합니다.

yarn run lint:prettier:staged

Prettier로 스테이지된 모든 파일(git diff 기반)을 검사하고 수동 업데이트가 필요한 파일을 콘솔에 출력합니다.

yarn run lint:prettier

Prettier로 모든 파일을 검사하고 수동 업데이트가 필요한 파일을 콘솔에 출력합니다.

yarn run lint:prettier:fix

Prettier로 리포지터리의 모든 파일을 포맷팅합니다.

VS Code 설정#

Prettier를 기본 포매터로 선택#

Prettier를 포매터로 선택하려면 사용자 또는 워크스페이스 설정에 다음 속성을 추가합니다:

{
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[graphql]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

저장 시 포맷팅#

파일을 저장할 때 Prettier로 자동 포맷팅하려면 사용자 또는 워크스페이스 설정에 다음 속성을 추가합니다:

{
  "[html]": {
    "editor.formatOnSave": true
  },
  "[javascript]": {
    "editor.formatOnSave": true
  },
  "[vue]": {
    "editor.formatOnSave": true
  },
  "[graphql]": {
    "editor.formatOnSave": true
  },
}

사용되지 않는 Vue provide 추적#

Vue 의존성 주입은 시간이 지남에 따라 낡아집니다. inject를 사용하는 컴포넌트가 리팩터링되거나 제거되면, 이에 대응하는 provide 항목이 이를 공급하는 el.dataset 읽기, HAML data: 속성, Ruby 헬퍼와 함께 그대로 남아 있는 경우가 많습니다. scripts/frontend/trace_provide_inject_usage.mjs 스크립트는 어떤 하위 컴포넌트도 주입하지 않는 provide 키를 찾아내므로, 죽은 연결 코드를 제거할 수 있습니다. 이 정리 작업의 예시는 머지 리퀘스트 !242664와 !242662를 참조하세요.

provider 파일 또는 파일 집합을 추적하려면, 하나 이상의 파일 경로나 glob과 함께 스크립트를 실행합니다. 이 스크립트는 PATH에 ripgrep(rg)이 있어야 하며, .vue와 .js 파일만 분석합니다:

node scripts/frontend/trace_provide_inject_usage.mjs <file|glob> [<file|glob>...]

예를 들어, 단일 진입점을 추적한 다음 디렉터리 전체를 추적하려면(셸이 확장하지 않도록 glob을 따옴표로 묶습니다):

node scripts/frontend/trace_provide_inject_usage.mjs app/assets/javascripts/ci/pipeline_details/pipeline_header.js

node scripts/frontend/trace_provide_inject_usage.mjs 'app/assets/javascripts/ci/**/*.js'

스크립트는 추적한 각 파일에 대한 분석 결과와 제거 후보의 최종 목록을 출력합니다. 각 provide 키에는 다음 판정 중 하나가 부여됩니다:

스크립트가 REMOVABLE 또는 LIKELY-REMOVABLE로 보고한 키를 제거하려면, 이를 공급하는 계층들을 차례로 작업하되, 다른 소비자가 여전히 사용하는 계층에서는 멈춥니다:

• provide: 항목을 제거합니다.

• el.dataset 읽기와 파생된 상수나 import를 제거하되, 진입점 내 다른 곳에서 사용되지 않을 때만 제거합니다. 해당 값이 스토어, 라우터, props, 또는 형제 애플리케이션에도 공급되는 경우에는 유지합니다.

• 다른 진입점이 동일한 마운트 요소를 읽지 않음을 확인한 후, HAML data: 속성을 제거합니다.

• app/와 ee/app/ 양쪽에서 다른 호출자가 있는지 확인한 후, 속성 값을 만드는 Ruby 헬퍼를 제거합니다.

• 제거된 키를 검증하는 RSpec 및 Jest 스펙을 업데이트합니다.

하위 컴포넌트가 여전히 주입하는 provide를 제거하면 런타임에 injection not found 오류가 발생하므로, 영향을 받는 페이지를 로드하거나 해당 기능 스펙을 실행하여 제거가 안전한지 확인하세요. 각 변경은 단일 provider 파일로 범위를 제한합니다.