• 규칙 인라인 비활성화
• 새로운 RuboCop cops 생성
• Cop 유예기간
• 새로운 cop 또는 cop 변경 제안
• 새로운 cop 활성화
• 차단된 offenses
  • RuboCop 노드 패턴
• RuboCop 예외 해결
• 주기적으로 RuboCop todo 파일 생성
• 기존 RuboCop 예외 확인

RuboCop 규칙 개발 지침

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

로컬에서 bundle exec rubocop --parallel 명령을 사용하여 어떤 offenses가 있는지 확인할 수 있습니다. CI에서는 이를 static-analysis 작업에 의해 자동으로 확인합니다.

또한 Solargraph gem을 사용하여 지원되는 IDE에 RuboCop을 통합할 수 있습니다. RuboCop을 통합하세요.

우리가 결정하지 않은 RuboCop 규칙에 대해서는 루비 스타일 가이드에 따라 우리의 스타일로 구체적인 루비를 작성하세요.

리뷰어/유지보수자는 스타일에 대해 너무 까다롭지 않고 관대해야 합니다.

일부 RuboCop 규칙은 비활성화되어 있고, 이에 대해 리뷰어/유지보수자는 저자에게 한 스타일을 사용하도록 요청해서는 안 됩니다. 둘 다 허용되기 때문에 이는 이상적인 상황이 아닙니다. 왜냐하면 이는 bike-shedding을 위한 공간을 만들어 둔 것입니다. 이상적으로는 스타일 관련 논의, 틀린 부분 지적 또는 리뷰에서의 번복을 피하기 위해 모든 RuboCop 규칙을 활성화해야 합니다. GitLab 루비 스타일 가이드에는 리뷰에서 자주 나오고 강제되지 않는 스타일의 비대한 목록이 포함되어 있습니다.

덧붙여, 우리는 전용 테스트 스타일 가이드 및 모범 사례를 갖고 있습니다.

규칙 인라인 비활성화

기본적으로 RuboCop 규칙은 인라인으로 비활성화되어서는 안 됩니다, 왜냐하면 이는 규칙이 코드베이스에 적용하려는 합의된 코드 표준을 무효화하기 때문입니다.

만약 인라인 비활성화를 사용해야 한다면, 비활성화하는 규칙이 있는 같은 줄에 그 이유를 코드 코멘트로 제공하세요.

더 많은 컨텍스트가 이 인라인 비활성화 코멘트 위에 코드 코멘트로 들어갈 수 있습니다. 상세한 컨텍스트를 제공하기 위해 리소스(이슈, 에픽, …)에 링크를 제공하여 장황한 코드 코멘트를 줄일 수 있습니다.

임시 인라인 비활성화에는 rubocop:todo를 사용하고 계속되는 이슈에 링크를 제공합니다.

예를 들면:

# bad
module Types
  module Domain
    # rubocop:disable Graphql/AuthorizeTypes
    class SomeType < BaseObject
      if condition # rubocop:disable Style/GuardClause
        # more logic...
      end

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

# good
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에서 정리
        # more logic...
      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 cops 생성

일반적으로 린팅 규칙을 프로그램적으로 강제하는 것이 bike-shedding을 줄이는 데 더 좋습니다.

이를 위해, 우리는 코드베이스에 새로운 RuboCop 규칙을 만들 것을 권장합니다.

특정 스타일을 강제하기 위해 새로운 cop을 추가하기 전에 팀과 논의하는 것이 중요합니다.

우리는 여러 루비 코드베이스에서 cops를 유지하고 있으며, 그 중 일부는 GitLab 애플리케이션에만 특정되어 있지 않습니다. 여러 애플리케이션에 적용할 수 있는 새로운 cop을 만들 때는 해당 cop을 우리의 gitlab-styles gem에 추가하는 것을 권장합니다. 만약 cop이 주로 GitLab 애플리케이션에만 적용되는 규칙을 대상으로 한다면, GitLab에 추가해야 합니다.

Cop 유예기간

만약 유예기간이 YAML 구성에서 정의된 상태로 활성화되어 있고 유효한 경고가 1주일 동안 #f_rubocop 채널에서 들어오지 않는다면, 유예기간을 안전하게 해제할 수 있습니다.

기본 브랜치에서 유예기간의 cops에서 오는 offenses는 RuboCop CI 작업을 실패시키지 않습니다. 대신, 작업은 #f_rubocop Slack 채널에 알립니다. 그러나 다른 브랜치에서는 RuboCop 작업이 실패합니다.

새로운 cop 또는 cop 변경 제안

새로운 cop을 강제하거나 기존의 cop 구성을 변경하는 제안을 하려면 gitlab-styles 병합 요청 템플릿 또는 gitlab 병합 요청 템플릿 를 사용하세요. 이 템플릿을 사용하면 새로운 규칙의 결과에 대해 피드백을 주도록 모든 유지보수자를 격려하며, 새로운 규칙의 결과로 인해 생기는 결과를 구조화된 방식으로 전달할 수 있습니다.

새로운 cop 활성화

1. .rubocop.yml에서 새로운 cop을 활성화하세요 (gitlab-styles를 통해 이미 활성화된 경우 제외).
2. 새로운 cop을 위한 TODO 생성.
3. 신규 cop을 유예기간으로 설정하세요.
4. #f_rubocop Slack 채널에서 1주일 동안 소리가 없을 경우, 유예기간를 제거하기 위한 이슈를 만드세요. 예시 확인.

차단된 offenses

캅스의 grace period에서 잠정적으로 offenses가 차단될 때, #f_rubocop Slack 채널은 2시간마다 알림 메시지를 받습니다.

이 문제를 해결하려면:

1. 연결된 CI 작업에서 차단된 offenses를 가진 cops를 찾으세요.
2. 이러한 cops에 대한 TODO 생성하세요.

RuboCop 노드 패턴

Ruby의 AST에 맞는 노드 패턴을 생성할 때, scripts/rubocop-parse를 사용할 수 있습니다. 이는 Ruby 식의 AST를 표시하여 matcher를 생성하는 데 도움이 됩니다. 또한 !97024도 참조하세요.

RuboCop 예외 해결

RuboCop 예외의 수가 기본 exclude-limit of 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 offenses가 시간이 지남에 따라 자동으로 수정됩니다. 이러한 offenses가 재도입되는 것을 피하기 위해, 우리는 주기적으로 .rubocop_todo 파일을 다시 생성합니다.

이를 위해 housekeeper gem를 사용합니다. 이는 .rubocop_todo 파일을 다시 생성하고, 머지 요청을 생성합니다. 리뷰어는 생성된 머지 요청을 무작위로 할당받습니다.

로컬로 keep를 실행하려면 다음 단계를 따르고 bundle exec gitlab-housekeeper -k Keeps::GenerateRubocopTodos를 실행하세요.

기존 RuboCop 예외 확인

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

이를 통해 일상적인 작업 주기 중에 기존 RuboCop 예외를 확인하고 중간에 고칠 수 있습니다.

참고: .rubocop_todo/**/*.yml대신에 .rubocop.yml에 Include 및 영구적인 Exclude를 정의하세요.