인라인에서 규칙 비활성화
새로운 RuboCop 경찰 만들기
Cop 유예 기간
새로운 cop 제안 또는 cop 변경
새로운 cop 활성화
침묵된 위반 사항
- RuboCop 노드 패턴
RuboCop 예외 해결
정기적으로 RuboCop todo 파일 생성
기존 RuboCop 예외 공개

RuboCop 규칙 개발 가이드라인

우리 코드베이스 스타일은 RuboCop에 의해 정의되고 강제됩니다.

로컬에서 위반 사항을 확인하려면 bundle exec rubocop --parallel을 사용하세요.

CI에서는 static-analysis 작업에 의해 자동으로 확인됩니다.

또한, 지원되는 IDE에 RuboCop를 통합하려면 Solargraph gem을 사용할 수 있습니다.

우리가 결정하지 않은 RuboCop 규칙에 대해서는 관용적인 Ruby 스타일을 작성하기 위해 Ruby 스타일 가이드를 따르세요.

검토자/유지 관리자들은 스타일에 대해 관대해야 하며 지나치게 세부적이지 않아야 합니다.

일부 RuboCop 규칙은 비활성화되어 있으며, 이에 대해 검토자/유지 관리자들은 저자에게 한 가지 스타일을 사용하라고 요구해서는 안 됩니다. 두 가지 모두 수용됩니다. 이는 바이크 쉐딩이 발생할 여지를 남기므로 이상적인 상황은 아닙니다. 이상적으로는 모든 RuboCop 규칙을 활성화하여 스타일 관련 논의나 세부 사항에 대한 피드백을 피해야 합니다. GitLab Ruby 스타일 가이드에는 검토에서 자주 발생하지만 강제되지 않는 스타일의 비포괄적인 목록이 포함되어 있습니다.

추가로, 우리는 전용 테스트 특정 스타일 가이드 및 모범 사례를 가지고 있습니다.

인라인에서 규칙 비활성화

기본적으로 RuboCop 규칙은 인라인에서 비활성화해서는 안 됩니다.

이는 규칙이 코드베이스에 적용하려고 하는 합의된 코드 표준을 무효화하기 때문입니다.

인라인 비활성화를 사용해야 하는 경우 규칙이 비활성화된 동일한 줄에 코드 주석으로 이유를 제공하세요.

더 많은 문맥은 이 인라인 비활성화 주석 위의 코드 주석에 추가될 수 있습니다. 장황한 코드 주석을 줄이기 위해 리소스(이슈, 에픽 등)를 링크하여 자세한 문맥을 제공하세요.

일시적인 인라인 비활성화를 위해 rubocop:todo를 사용하고 후속 이슈 또는 에픽을 링크하세요.

예를 들면:

# 나쁨
module Types
  module Domain
    # rubocop:disable Graphql/AuthorizeTypes
    class SomeType < BaseObject
      if condition # rubocop:disable Style/GuardClause
        # 더 많은 로직...
      end

      object.public_send(action) # rubocop:disable GitlabSecurity/PublicSend
    end
    # rubocop:enable Graphql/AuthorizeTypes
  end
end

# 좋음
module Types
  module Domain
    # rubocop:disable Graphql/AuthorizeTypes -- 부모 엔티티에서 이미 인증됨
    class SomeType < BaseObject
      if condition # rubocop:todo Style/GuardClause -- https://gitlab.com/gitlab-org/gitlab/-/issues/1234567890를 통해 정리
        # 더 많은 로직...
      end

      # 이 시점에서 `action`은 `public_send`에서 안전하게 사용할 수 있습니다.
      # https://gitlab.com/gitlab-org/gitlab/-/issues/123457890을 참조하세요.
      object.public_send(action) # rubocop:disable GitlabSecurity/PublicSend -- 사용자 입력 확인됨
    end
    # rubocop:enable Graphql/AuthorizeTypes
  end
end

새로운 RuboCop 경찰 만들기

일반적으로, 린트 규칙은 프로그램적으로 강제하는 것이 더 좋습니다. 이는 앞서 언급한 바이크 쉐딩을 줄이는 데 도움이 됩니다.

이를 위해 우리는 코드베이스에 새로운 RuboCop 규칙의 생성을 장려합니다.

주어진 스타일을 강제하기 위해 새로운 경찰을 추가하기 전에 팀과 논의하세요.

우리는 여러 Ruby 코드베이스에서 경찰을 유지 관리하고 있으며, 이 중 일부는 GitLab 애플리케이션에 특정되지 않습니다.

여러 애플리케이션에 적용될 수 있는 새로운 경찰을 생성할 경우, gitlab-styles gem에 추가하는 것을 권장합니다.

해당 경찰이 주요 GitLab 애플리케이션에만 적용되는 규칙을 목표로 하는 경우, GitLab에 추가해야 합니다.

Cop 유예 기간

Cop은 _유예 기간_에 있을 때, 활성화되어 있으며 TODO YAML 구성에서 Details: grace period가 정의되어 있습니다.

기본 브랜치에서 유예 기간에 있는 cop의 위반 사항은 RuboCop CI 작업을 실패시키지 않습니다. 대신, 작업은 #f_rubocop 슬랙 채널에 알림을 보냅니다. 그러나 다른 브랜치에서는 RuboCop 작업이 실패합니다.

#f_rubocop 채널에서 1주 동안 경고가 없으면 유예 기간을 안전하게 해제할 수 있습니다.

새로운 cop 제안 또는 cop 변경

새로운 cop을 시행하거나 기존 cop 구성을 변경하기 위한 제안을 하려면 gitlab-styles 병합 요청 템플릿 또는 gitlab 병합 요청 템플릿을 사용하세요. 이 규칙을 추가하고 싶은 위치에 따라 선택합니다. 이 템플릿을 사용하면 모든 유지 관리자가 우리가 선호하는 스타일에 대해 피드백을 제공할 수 있도록 장려하며, 새 규칙의 결과를 전달하는 구조화된 방법을 제공합니다.

새로운 cop 활성화

.rubocop.yml에서 새로운 cop을 활성화합니다 (이미 gitlab-styles를 통해 설정되지 않은 경우).
새 cop을 위한 TODO 생성합니다.
새 cop을 grace period로 설정합니다.
TODO를 수정하고 커뮤니티 기여를 장려하기 위한 이슈를 생성합니다 (via ~"quick win" 및/또는 ~"Seeking community contributions"). 몇 가지 예를 보세요.
#f_rubocop 슬랙 채널에서 1주일 동안 침묵이 지속된 후 grace period를 제거하기 위한 이슈를 생성합니다. 예시를 보세요.

침묵된 위반 사항

유예 기간에 있는 cop의 위반 사항이 침묵되면, #f_rubocop 슬랙 채널은 2시간마다 알림 메시지를 받습니다.

이 문제를 해결하려면:

링크된 CI 작업에서 침묵된 위반 사항이 있는 cop을 찾습니다.
해당 cop을 위한 TODO 생성합니다.

RuboCop 노드 패턴

Ruby의 AST에 맞추기 위해 노드 패턴을 생성할 때, scripts/rubocop-parse를 사용할 수 있습니다. 이것은 Ruby 표현식의 AST를 표시하여 매처를 생성하는 데 도움을 줍니다. 자세한 내용은 !97024도 참고하세요.

RuboCop 예외 해결

RuboCop 예외의 수가 기본 exclude-limit인 15를 초과할 경우, 여러 커밋에 걸쳐 예외를 해결하고 싶을 수 있습니다. 혼란을 최소화하기 위해 예외 목록을 통해 진행 상황을 추적해야 합니다.

특정 RuboCop 규칙에 대한 초기 목록 또는 목록을 생성하는 선호하는 방법은 Rake 작업 rubocop:todo:generate를 실행하는 것입니다:

# 초기 목록
bundle exec rake rubocop:todo:generate

# 특정 RuboCop 규칙에 대한 목록
bundle exec rake 'rubocop:todo:generate[Gitlab/NamespacedClass,Lint/Syntax]'

이 Rake 작업은 .rubocop_todo/의 예외 목록을 생성하거나 업데이트합니다. 예를 들어, RuboCop 규칙 Gitlab/NamespacedClass의 구성은 .rubocop_todo/gitlab/namespaced_class.yml에 위치해 있습니다.

Rake 작업을 실행한 후에 .rubocop_todo/의 변경 사항을 커밋해야 합니다.

정기적으로 RuboCop todo 파일 생성

코드 변경으로 인해 시간이 지나면서 일부 RuboCop 위반이 자동으로 수정됩니다. 이러한 위반이 다시 나타나는 것을 피하기 위해, 우리는 주기적으로 .rubocop_todo 파일을 재생성합니다.

이 목적으로 우리는 housekeeper gem을 사용합니다. 이는 .rubocop_todo 파일을 재생성하고 병합 요청을 생성합니다. 검토자는 생성된 병합 요청을 검토하기 위해 무작위로 할당됩니다.

로컬에서 유지 관리를 실행하려면 이 단계를 따르세요 그리고 bundle exec gitlab-housekeeper -k Keeps::GenerateRubocopTodos를 실행하세요.

기존 RuboCop 예외 공개

.rubocop_todo.yml 및 .rubocop_todo/**/*.yml을 통해 제외된 코드에서 기존 RuboCop 예외를 공개하려면, 환경 변수 REVEAL_RUBOCOP_TODO를 1로 설정하세요.

이 설정은 일상적인 작업 주기에서 기존 RuboCop 예외를 공개하고 그에 따라 수정할 수 있게 합니다.

노트:

.rubocop.yml 대신 .rubocop_todo/**/*.yml에 Includes 및 영구적인 Excludes를 정의하세요.