각 Sidekiq 워커, Batched Background 마이그레이션, 컨트롤러 액션, 테스트 예제, API 엔드포인트는 feature_category 속성을 선언해야 합니다. 이 속성은 각 대상을 기능 카테고리에 매핑합니다. 이는 오류 예산 관리, 알림 라우팅, 팀 귀속을 위한 것입니다.

기능 카테고리 목록은 config/feature_categories.yml 파일에서 확인할 수 있습니다. 이 파일은 GitLab 핸드북과 그 밖의 GitLab 리소스에서 사용하는 stages.yml 데이터 파일로부터 생성됩니다.

config/feature_categories.yml 업데이트#

GitLab의 스테이지, 그룹, 제품 카테고리에 새 기능이 추가되는 경우가 있습니다. 이럴 때는 scripts/update-feature-categories를 실행해 config/feature_categories.yml을 자동으로 갱신할 수 있습니다. 이 스크립트는 stages.yml 을 가져와 파싱한 뒤 새 버전의 파일을 생성하며, 이 파일을 리포지터리에 커밋해야 합니다.

현재 feature_categories.yml 파일은 Observability 팀이 관리합니다. 파일이 오래되면 이 팀에 Slack으로 자동 알림이 전달됩니다.

Gemfile#

각 Ruby gem 의존성마다 어떤 기능 카테고리가 그 의존성을 필요로 하는지 지정해야 합니다. 이렇게 하면 소유권이 분명해지고, 해당 기능을 소유한 그룹에 업그레이드를 맡길 수 있습니다.

Tooling 기능 카테고리#

Developer Experience 내부 도구에는 feature_category: :tooling을 사용합니다. 예를 들어 knapsack과 gitlab-crystalball은 둘 다 CI에서 RSpec 테스트 스위트를 실행하는 데 쓰이며 어떤 제품 그룹에도 속하지 않습니다.

Test platform 기능 카테고리#

엔드투엔드 테스트 인프라와 관련된 gem은 Development Experience 섹션이 관리합니다. 이때는 feature_category: :test_platform 레이블을 사용합니다. 예를 들어 capybara는 UI가 관여하는 테스트를 실행하기 위해 Gemfile과 qa/Gemfile 양쪽에 정의되어 있습니다. 이러한 gem은 특정 제품 그룹에 속하지 않습니다.

Rails platform 기능 카테고리#

Rails 코어 프레임워크 gem은 주로 Backend Maintainer가 관리합니다. 예를 들어 rails와 zeitwerk는 :rails_platform으로 정의해야 합니다.

Shared 기능 카테고리#

gem을 잘 관리하기 위한 노력의 일환으로, 모든 gem은 구체적인 기능 카테고리를 사용해야 합니다. gem의 소유권이 불분명하다면 #backend_maintainers 채널에 문의합니다.

Sidekiq 워커#

선언에는 다음과 같이 feature_category 클래스 메서드를 사용합니다.

class SomeScheduledTaskWorker
  include ApplicationWorker

  # Declares that this worker is part of the
  # `continuous_integration` feature category
  feature_category :continuous_integration

  # ...
end

feature_category로 지정하는 기능 카테고리는 config/feature_categories.yml에 정의되어 있어야 합니다. 그렇지 않으면 스펙이 실패합니다.

기능 분류에서 Sidekiq 워커 제외#

모든 기능에서 공통으로 쓰이는 일부 Sidekiq 워커는 하나의 카테고리에 매핑할 수 없습니다. 이러한 워커는 다음과 같이 feature_category :not_owned 선언으로 표시해야 합니다.

class SomeCrossCuttingConcernWorker
  include ApplicationWorker

  # Declares that this worker does not map to a feature category
  feature_category :not_owned # rubocop:disable Gitlab/AvoidFeatureCategoryNotOwned

  # ...
end

"not owned" 로 표시된 워커는 가능한 경우 메트릭과 로그에서 호출자(워커 또는 HTTP 엔드포인트)의 카테고리를 사용합니다. 예를 들어 ReactiveCachingWorker는 메트릭과 로그에서 여러 기능 카테고리를 가질 수 있습니다.

Batched background 마이그레이션#

소요 시간 지침에 따라 오래 걸리는 마이그레이션은 batched background 마이그레이션으로 분리합니다. 이때 다음과 같이 feature_category를 정의해야 합니다.

# Filename: lib/gitlab/background_migration/my_background_migration_job.rb

class MyBackgroundMigrationJob < BatchedMigrationJob
  feature_category :gitaly

  #...
end

Rails 컨트롤러#

컨트롤러 액션의 기능 카테고리는 feature_category 클래스 메서드로 지정할 수 있습니다.

컨트롤러 전체에 기능 카테고리를 지정하려면 다음과 같이 작성합니다.

class Boards::ListsController < ApplicationController
  feature_category :kanban_boards
end

두 번째 인수를 사용하면 기능 카테고리를 특정 액션 목록으로 제한할 수 있습니다.

class DashboardController < ApplicationController
  feature_category :team_planning, [:issues, :issues_calendar]
  feature_category :code_review_workflow, [:merge_requests]
end

두 방식을 섞어 쓸 수는 없습니다. 컨트롤러에 카테고리가 두 개 이상이면 모든 액션을 하나도 빠짐없이 나열해야 합니다.

기능 분류에서 컨트롤러 액션 제외#

액션을 기능 카테고리에 연결할 수 없는 드문 경우에는 not_owned 기능 카테고리를 사용할 수 있습니다.

class Admin::LogsController < ApplicationController
  feature_category :not_owned
end

기능 카테고리 유효성 검사#

spec/controllers/every_controller_spec.rb는 정의된 모든 라우트를 순회하며, 컨트롤러의 모든 액션에 카테고리가 할당되어 있는지 확인합니다.

이 스펙은 사용된 기능 카테고리가 알려진 값인지, 구성에 사용된 액션이 여전히 라우트로 존재하는지도 검증합니다.

API 엔드포인트#

GraphQL API는 현재 not_owned로 분류되어 있습니다. 당분간 별도의 지정은 필요하지 않습니다. 자세한 내용은 gitlab-com/gl-infra/scalability#583을 참고합니다.

Grape API 엔드포인트도 Rails 컨트롤러와 마찬가지로 feature_category 클래스 메서드를 사용할 수 있습니다.

module API
  class Issues < ::API::Base
    feature_category :team_planning
  end
end

두 번째 인수로 특정 라우트에 대한 기능 카테고리를 지정할 수 있습니다.

module API
  class Users < ::API::Base
    feature_category :user_profile, ['/users/:id/custom_attributes', '/users/:id/custom_attributes/:key']
  end
end

또는 액션 자체에 기능 카테고리를 지정할 수도 있습니다.

module API
  class Users < ::API::Base
    get ':id', feature_category: :user_profile do
    end
  end
end

Rails 컨트롤러와 마찬가지로, 클래스 안의 모든 액션이 같은 카테고리를 쓰는 경우가 아니라면 API 클래스는 모든 액션에 대해 카테고리를 지정해야 합니다.

RSpec 예제#

RSpec 예제마다 기능 카테고리 메타데이터를 설정해야 합니다. 이 정보는 불안정한 테스트 이슈에서 해당 기능을 소유한 그룹을 식별하는 데 사용됩니다.

feature_category는 config/feature_categories.yml에 있는 값이어야 합니다.

feature_category 메타데이터는 다음 위치에 설정할 수 있습니다.

• 최상위 RSpec.describe 블록.
• describe 블록.

한 파일에서 기능 카테고리가 여러 개 확인된다면 파일을 나누는 것을 검토합니다.

예를 들면 다음과 같습니다.

RSpec.describe Admin::Geo::SettingsController, :geo, feature_category: :geo_replication do

feature_category가 설정되지 않은 예제는 로컬 환경에서 실행할 때 경고를 표시합니다.

이 경고를 끄려면 RSpec 테스트를 실행할 때 RSPEC_WARN_MISSING_FEATURE_CATEGORY=false를 사용합니다.

RSPEC_WARN_MISSING_FEATURE_CATEGORY=false bin/rspec spec/<test_file>

또한 RSpec/FeatureCategory RuboCop 규칙으로 위반 사항을 표시합니다.

Tooling 기능 카테고리#

Engineering Productivity 내부 도구에는 feature_category: :tooling을 사용합니다.

예시는 spec/tooling/danger/specs_spec.rb에서 확인할 수 있습니다.

Shared 기능 카테고리#

불안정한 테스트와 격리된 테스트의 자동화를 정비하려는 노력의 일환으로, 모든 스펙은 구체적인 기능 카테고리를 사용해야 합니다. 스펙의 소유권이 불분명하다면 #g_test_governance 팀에 문의합니다. shared 소유권을 가진 기존 테스트의 이관에 관한 자세한 내용은 이 이슈를 참고합니다.

Admin 섹션#

Admin 섹션에 새 부분을 추가할 때도 기능 카테고리 지정은 똑같이 중요합니다. 과거에는 Admin 섹션이 코드에서 not_owned로 표시되는 경우가 많았습니다. 이제는 Admin 섹션에 새로 추가하는 항목마다 feature_category 표기로 올바르게 명시해야 합니다.