조직 기능은 조직 플래그(organization flag) 뒤에 게이트한 다음, 그 플래그를 고정된 공유 스테이지(stage) 사다리를 따라 올리는 방식으로 출시합니다. 스테이지는 Experimental, Beta, Limited Availability(LA), GA입니다.

이 모델은 한 가지 아이디어에 기반합니다. 기능의 대상 사용자는 오직 넓어지기만 한다는 것입니다. 대상 사용자는 두 축을 따라 넓어집니다. 세그먼트는 누가 기능에 접근할 수 있는지로, Organizations 팀에서 시작해 GitLab 팀 멤버와 옵트인한 고객으로, 다시 점점 더 많은 고객으로, 마지막에는 모두에게로 확장됩니다. 플랫폼은 기능이 어디에서 실행되는지로, GitLab.com에서 시작해 GA 시점에는 GitLab Self-Managed와 GitLab Dedicated까지 확장됩니다. 각 스테이지는 그렇게 넓어지는 면 위의 한 지점입니다. 더 높은 스테이지는 두 축 중 하나 또는 양쪽 모두에서 대상 사용자를 넓히며, 결코 좁히지 않습니다.

여러분이 바꾸는 것은 오직 하나, 스테이지뿐입니다. 스테이지는 스테이지당 하나씩 존재하는, 작고 고정된 공유 스테이지 플래그(stage flag) 집합(org_stage_*)으로 뒷받침되며, 각 플래그에는 해당 스테이지의 대상 사용자와 롤아웃이 이미 구성되어 있습니다. 플래그를 새로 만들거나 그 액터 또는 백분율을 조정하지 않습니다. 기능을 진전시키려면 머지 리퀘스트에서 해당 조직 플래그의 스테이지를 올리면 되고, 그러면 그 스테이지의 롤아웃을 상속합니다. 이것이 각 기능이 자기 기능 플래그를 소유하고 자기 롤아웃을 직접 구동하는 일반적인 GitLab 기능 플래그 워크플로와 이 프로세스가 달라지는 핵심 지점입니다.

구체적인 내용은 핸드북에 있습니다. 스테이지, 각 스테이지의 대상 사용자, 목표 플랫폼, 롤아웃 규칙이 그렇습니다. Organizations release stages를 참조하세요. 그 페이지가 진실 공급원이며, 제품과 디자인을 포함해 Organizations에서 일하는 모든 사람을 대상으로 작성되었습니다. 이 페이지는 엔지니어링 가이드입니다.

모든 기능이 아직 이 프로세스를 따르는 것은 아닙니다. 오늘날 모든 경로가 릴리스 레이어에 올라와 있지는 않은 기능인 조직 생성에 대한 감사 내용은 조직이 생성되는 방식을 참조하세요.

기능을 릴리스하는 데는 네 단계가 있습니다:

• 릴리스 레이어로 기능을 게이트합니다.

• 시작 스테이지로 조직 플래그를 등록합니다.

• 릴리스 spec 헬퍼로 기능을 테스트합니다.

• Stable에 도달할 때까지 스테이지를 따라 진전시킵니다.

기능 게이트하기#

기능 코드와 기능 플래그 라이브러리 사이에 위치하는 릴리스 레이어 Organizations::Release로 기능을 감쌉니다. 기능 플래그를 직접 확인하지 말고, 조직 플래그가 활성화되어 있는지 이 레이어에 물어보세요:

return unless Organizations::Release.enabled?(:ui_for_organizations, actor)

이 레이어는 조직 플래그의 스테이지를 조회한 뒤 해당 스테이지의 공유 스테이지 플래그에 대해 액터를 검사합니다. 또한 앞선 캐스케이딩 스테이지 플래그들도 확인하므로, 결과가 이전 스테이지에서 나올 수도 있습니다. 앞선 스테이지는 앞으로 캐스케이드됩니다를 참조하세요. 액터는 스테이지 플래그가 롤아웃되는 대상으로, 현재 사용자나 조직 같은 것입니다. 스테이지 플래그의 인스턴스 전체 게이트를 확인하려면 nil을 전달합니다.

이 레이어는 직접적인 Feature.enabled? 확인과 마찬가지로 액터를 기능 플래그 라이브러리로 그대로 전달합니다. 공유 스테이지 플래그는 백분율 롤아웃 시 액터 유형별로 버킷을 나누므로, 하나의 조직 플래그에 대해서는 모든 호출 지점에서 일관된 액터 유형을 전달하세요. 스테이지 플래그를 운영하는 방식을 참조하세요.

앞선 스테이지는 앞으로 캐스케이드됩니다#

어떤 스테이지에서 기능을 볼 수 있는 액터는 그 기능이 이후 스테이지로 진행되어도 그 접근 권한을 유지합니다. 대상 사용자는 오직 넓어지기만 하므로, 앞선 더 작은 대상 사용자가 배제되는 일은 없습니다. 따라서 Beta 스테이지의 기능은 Beta 대상 사용자뿐 아니라 Experimental 대상 사용자에게도 활성화되어 있습니다.

Organizations::Release.enabled?가 이를 반영합니다. 이 메서드는 플래그 자신의 스테이지 플래그와 앞선 모든 캐스케이딩 스테이지 플래그를 확인합니다. 캐스케이드되는 것은 Experimental과 Beta뿐입니다. LA 스테이지들은 독립적인 백분율 버킷으로 롤아웃되어 중첩되지 않으며, GA는 이미 모두에게 켜져 있습니다.

프런트엔드에 플래그 노출하기#

프런트엔드 코드를 게이트하려면, push_frontend_feature_flag로 기능 플래그를 푸시하듯이 컨트롤러에서 조직 플래그를 푸시합니다:

push_frontend_organization_release(:ui_for_organizations, actor)

이 헬퍼는 레이어를 통해 조직 플래그를 해석한 다음 그 결과를 조직 플래그 자신의 이름으로 푸시합니다. 프런트엔드 코드는 gon.features.uiForOrganizations를 읽으며 뒷단의 스테이지 플래그와 분리된 상태를 유지합니다. 기능을 다른 스테이지로 진전시켜도 프런트엔드 변경은 필요하지 않습니다.

조직 플래그 등록하기#

config/organizations_release.yml에 조직 플래그를 선언합니다:

flags:
  - name: ui_for_organizations
    description: Browse and manage an organization through its dedicated UI.
    stage: experimental

• name: Organizations::Release.enabled?에 전달하는 식별자입니다.

• stage: 기능이 시작하는 스테이지로, 보통 experimental입니다. experimental, beta, la_25, la_50, la_75, la_100, ga 중 하나입니다.

기능 테스트하기#

모든 spec에서 사용할 수 있는 stub_organization_release로 spec에서 조직 플래그를 토글합니다:

stub_organization_release(:ui_for_organizations, enabled: true)
stub_organization_release(:ui_for_organizations, enabled: false)

일반 기능 플래그와 마찬가지로 뒷단의 스테이지 플래그는 테스트에서 기본적으로 활성화되어 있으므로, enabled: false로 비활성화하지 않는 한 게이트된 코드가 실행됩니다.

이 헬퍼는 레지스트리를 통해 조직 플래그를 현재 그것을 뒷받침하는 스테이지 플래그로 해석한 다음, 그 스테이지 플래그를 stub 처리합니다. spec은 스테이지를 하드코딩하지 않으므로, 기능이 다른 스테이지로 진전되어도 계속 올바른 플래그를 테스트합니다.

이 헬퍼는 뒷단의 스테이지 플래그를 토글하므로, 해당 기능만이 아니라 스테이지 전체를 활성화하거나 비활성화합니다. 같은 스테이지에 있는 모든 조직 플래그가 함께 뒤집히며, 이는 프로덕션의 공유 스테이지 플래그와 동일합니다. 기능을 비활성화할 때 헬퍼는 앞선 캐스케이딩 스테이지 플래그도 함께 해제하므로, 캐스케이드 때문에 기능이 켜진 채로 남지 않습니다.

스테이지를 따라 진전시키기#

기능의 stage를 한 번에 한 단계씩 올려 진전시킵니다. 각 변경은 하나의 머지 리퀘스트입니다:

flowchart LR
    Add["Register flag<br>stage: experimental"] --> beta --> la_25 --> la_50 --> la_75 --> la_100 --> ga --> Stable["Stable<br>remove the flag"]

모든 스테이지가 필수는 아닙니다. 경로는 핸드북이 정의합니다. 요약하면 다음과 같습니다:

기능을 롤백하려면 같은 방식으로 조직 플래그의 stage를 낮춥니다.

GA에 도달하려면 org_stage_ga를 default_enabled: true로 출시하는 것도 필요합니다. 그 스테이지 플래그가 기능을 GitLab Self-Managed와 GitLab Dedicated로 실어 나릅니다.

Stable에 도달한다는 것은 시스템에서 완전히 벗어난다는 뜻입니다. 조직 플래그의 config/organizations_release.yml 항목을 제거하고, 그 Organizations::Release.enabled? 호출 지점을 조건 없는 동작으로 교체합니다. 공유 스테이지 플래그는 그 스테이지에 있는 다른 조직 플래그를 위해 그대로 남습니다. Stable은 여러분이 설정하는 stage 값이 아닙니다.

위험도가 높은 기능은 공유 스테이지 플래그를 아예 건너뛰고 자체 기능 플래그를 사용할 수 있습니다.

스테이지 플래그를 운영하는 방식#

보통은 이 부분을 건드릴 일이 없습니다. 기능을 진전시키는 것은 stage 변경입니다(스테이지를 따라 진전시키기 참조). 이 섹션은 공유 스테이지 플래그가 어떻게 설정되고 유지되는지에 대한 내용입니다.

각 스테이지는 lib/organizations/release/stage.rb에 정의된 하나의 공유 ops 스테이지 플래그에 매핑됩니다:

여기의 ChatOps 명령은 개별 조직 플래그가 아니라 이 공유 스테이지 플래그를 구성합니다. 스테이지 플래그의 구성은 그 스테이지에 있는 모든 조직 플래그에 대해 동일합니다. 스테이지 플래그는 공유되므로, 그 스테이지의 모든 조직 플래그가 게이트를 공유하며 액터는 어느 게이트든 하나에 부합하면 기능을 보게 됩니다. Flipper는 스테이지 플래그의 게이트들을 논리 OR로 결합하므로, 하나의 스테이지 플래그가 여러 대상 사용자를 동시에 담당할 수 있습니다.

Experimental과 Beta 스테이지 플래그는 특정 액터를 활성화합니다:

/chatops run feature set --group=gitlab-org/organizations org_stage_experimental true
/chatops run feature set --group=a-customer-group org_stage_beta true

액터는 폴리모픽입니다. 특정 액터 게이트는 GitLab이 기능 플래그 액터로 지원하는 모든 유형(Feature::SUPPORTED_MODELS), 즉 조직, 사용자, 그룹 등을 받습니다. 특정 조직이나 특정 사용자처럼 기능을 받아야 하는 액터에 대해 스테이지 플래그를 활성화하세요. 액터 유형은 기능이 호출 지점에서 확인하는 것과 일치해야 하며, 그렇지 않으면 게이트가 결코 적중하지 않습니다.

LA 스테이지 플래그는 액터 백분율을 사용하며, 각 스테이지 플래그 이름에 있는 백분율로 설정됩니다:

/chatops run feature set org_stage_la_25 25 --actors
/chatops run feature set org_stage_la_50 50 --actors

시간 백분율이 아니라 액터 백분율을 사용하세요. 액터 백분율은 특정 액터를 롤아웃에 일관되게 포함하거나 제외하는 반면, 시간 백분율은 확인할 때마다 다시 추첨합니다.

공유 스테이지 플래그가 가지는 두 가지 결과가 있습니다:

• 액터 백분율은 확인 시점에 액터를 필요로 합니다. nil을 전달하는 확인은 불리언 게이트나 특정 액터 게이트로만 부합하며, 백분율 게이트로는 결코 부합하지 않습니다.

• 액터 백분율은 각 액터를 그 유형별로 버킷에 나눕니다. 같은 스테이지에 있는 두 조직 플래그가 한 요청 안에서 서로 다른 액터 유형으로 확인되면 롤아웃이 하나는 포함하고 다른 하나는 제외할 수 있으므로, 주어진 조직 플래그에 대해서는 일관된 액터 유형을 전달하세요.

GA 스테이지 플래그는 default_enabled: true로 출시되는 유일한 플래그입니다. 이 플래그는 핸드브레이크를 유지한 채 모든 배포에 도달합니다. 핸드브레이크는 GitLab.com과 Self-Managed에서는 동작하지만, 기능 플래그를 수정할 수 없는 GitLab Dedicated에서는 작동하지 않습니다.

릴리스 상태 표#

doc/development/organizations/release_status.md는 레지스트리로부터 생성되며 손으로 편집하지 않습니다. 스테이지를 변경한 후에는 다시 생성하세요:

bin/rake gitlab:organizations:release:docs

이 표는 Experimental부터 GA까지 현재 롤아웃 프로세스에 있는 조직 플래그를 보여 줍니다. Stable에 도달한 조직 플래그는 스테이지 플래그 시스템에서 벗어나 표에서 졸업합니다.

용어#

• 기능(Feature): Organizations 팀이 출시하는 제품 역량으로, 릴리스 프로세스에 있는 동안 게이트됩니다.

• 조직 플래그(Organization flag): 개발자가 config/organizations_release.yml에 선언하고 Organizations::Release.enabled?로 확인하는 항목입니다. 하나의 기능을 게이트하며 하나의 스테이지에 위치합니다.

• 스테이지(Stage): Experimental이나 GA 같은 릴리스 프로세스의 한 단계입니다.

• 스테이지 플래그(Stage flag): 스테이지당 하나씩 존재하는 공유 org_stage_* 기능 플래그 중 하나입니다. 한 스테이지에 있는 모든 조직 플래그는 그 스테이지의 스테이지 플래그로 게이트됩니다.