Merge Request 워크플로우

우리는 모든 사람으로부터 GitLab 코드, 테스트 및 문서의 수정 사항 및 개선 사항에 대한 Merge Request을 환영합니다. 커뮤니티 기여에 적합한 문제는 커뮤니티 기여를 찾는 중 라벨이 지정된 문제입니다. 하지만 원하는 문제에 대한 기여는 자유롭게 할 수 있습니다.

문제에서 작업하기

이슈를 찾으면 가능하다면 수정 사항 또는 개선 사항이 있는 Merge Request을 제출하고 테스트를 포함시키세요.

라벨이 지정되지 않은 새로운 기능을 추가하고 싶다면, (이미 없는 경우) 먼저 이슈를 작성하고 커뮤니티 기여를 찾는 중으로 라벨이 지정되도록 요청하는 댓글을 남기는 것이 좋습니다. 기능 제안 섹션을 참조하세요.

문제를 해결하는 방법을 모르지만 문제를 드러내는 테스트를 작성할 수 있다면, 해당 테스트도 수용할 것입니다. 일반적으로 회귀 테스트를 포함하는 버그 수정은 빠르게 Merge됩니다. 적절한 테스트가 없는 새로운 기능은 피드백을 받는 데 시간이 더 걸릴 수 있습니다.

GitLab 개발에 처음이라면(또는 웹 개발 전반에 처음이라면), 기여하는 방법 섹션을 참조하여 잠재적으로 쉬운 문제로 시작하세요.

Merge Request 소유권

이슈가 현재 마일스톤에 지정되어 있는 경우, 작업 중이어도 GitLab 팀 멤버가 해당 Merge Request을 마감 일 전에 작업을 완료하도록 하는 경우가 있습니다.

기여자가 더 이상 활발하게 작업을 하지 않는 제출된 Merge Request의 경우 다음을 할 수 있습니다:

Merge Request 코치 중 한 명이 Merge Request을 완료할 것으로 결정합니다.
Merge Request을 닫습니다.

이 결정은 제품 비전에 중요한 변경 내용인지를 기준으로 합니다. Merge Request 코치가 Merge Request을 완료하게 되면, ~coach will finish 라벨을 할당합니다.

팀 멤버가 커뮤니티 기여를 수용하면, 우리는 변경 로그 항목을 추가하여 기존 저자를 인정하고 해당 Merge Request 중 적어도 하나의 커밋에 원래 저자를 선택적으로 포함합니다.

기여자를 위한 Merge Request 가이드라인

기여 프로세스에 대한 지침은 튜토리얼: GitLab 기여하기를 참조하세요.

최상의 실천법

변경 사항이 복잡하다면, 코드 검토를 시작하기 바랍니다. 제품 관리자 또는 팀 구성원과 토의하는 것을 권장합니다. 코드를 제출하기 전에 MR에서 그들을 태그함으로써 이를 수행할 수 있습니다. 팀 구성원과 대화하는 것은 디자인 결정을 내릴 때 도움이 될 수 있습니다. 변경 내용의 의도를 전달하는 것도 Merge Request 리뷰를 신속히 하는 데 도움이 됩니다.
프로덕션 가용성에 영향을 줄 수 있다고 생각된다면 코드를 피처 플래그 뒤에 배치하는 것을 고려해보세요. 확실하지 않다면 피처 플래그 사용 시기 문서를 읽어보세요.
Merge Request에 대한 빠른 피드백이 필요하다면 핵심 팀의 누군가나 Merge Request 코치 중 한 명을 멘션하세요. 코드 리뷰를 받을 때와 Merge Request을 리뷰할 때는 코드 리뷰 지침을 염두에 두세요. 그리고 만약 코드가 데이터베이스에 변경을 가하는 경우 또는 고비용 쿼리를 실행하는 경우 데이터베이스 리뷰 지침을 확인하세요.

단순하게 유지하세요

작은 반복으로 살아가세요. 한 번에 하나의 MR에서의 변경 내용을 가능한 한 작게 유지하는 것을 권장합니다. 큰 기능을 기여하고 싶다면, 최소한의 변경 가능성 에 대해 신중히 생각해보세요. 기능을 두 개의 작은 MR로 나눌 수 있을까요? 백엔드/API 코드만 제출할 수 있을까요? 아주 간단한 UI로 시작할 수 있을까요? 리팩터링의 일부만 할 수 있을까요?

더 쉽게 검토되는 작은 MR은 더 높은 코드 품질과 함께 GitLab에게 더 중요합니다. MR이 작을수록 빠르게 Merge될 가능성이 높습니다. 이후에 기능을 향상하고 확장하기 위해 더 많은 MR을 보낼 수 있습니다. Kubernetes 팀의 PR 검토를 더 빠르게 받는 방법 문서에도 관련해서 좋은 포인트가 있습니다.

커밋 메시지 지침

커밋 메시지는 아래 지침을 따라야 합니다. Chris Beams의 Git 커밋 메시지를 작성하는 방법에서 설명한 이유로:

커밋 제목과 본문은 빈 줄로 구분되어야 합니다.
커밋 제목은 대문자로 시작되어야 합니다.
커밋 제목은 72자를 넘지 않아야 합니다.
커밋 제목은 마침표로 끝나지 않아야 합니다.
커밋 본문은 각 줄마다 72자를 넘지 않아야 합니다.
커밋 제목이나 본문에 이모지가 포함되어서는 안 됩니다.
3개 이상의 파일에서 30줄 이상의 변경을 하는 커밋은 이러한 변경 내용을 커밋 본문에 설명해야 합니다.
GitLab 외부에서 평문으로 표시되므로, 이슈, 마일스톤 및 Merge Request의 전체 URL을 사용해야 합니다.
Merge Request은 10개 이상의 커밋 메시지를 포함해서는 안 됩니다.
커밋 제목에는 적어도 3개의 단어가 있어야 합니다.

중요한 사항:

지침을 준수하지 않을 경우, MR이 위험(Danger) 검사를 통과하지 못할 수 있습니다.
만약 당신의 Merge Request이 “Applied suggestion to X files” 커밋을 포함한다면, 압축하여 Merge을 활성화하는 것을 고려하여 Danger가 해당 내용을 무시할 수 있게 할 수 있습니다.
[접두어] 형식의 접두어는 허용됩니다 (메시지 자체는 대문자이기만 하면 소문자로 되어도 상관없음). 예를 들어, danger: 행동 개선하기와 [API] 라벨 엔드포인트 개선은 유효한 커밋 메시지입니다.

이러한 표준이 중요한 이유

이러한 지침을 따르는 일관된 커밋 메시지는 히스토리를 더욱 가독성 있게 만듭니다.
간결한 표준 커밋 메시지는 시간 상의 두 지점 사이의 커밋을 리뷰할 때 배포나 ~"master:broken"의 중요 사항을 신속하게 식별하는 데 도움이 됩니다.

커밋 메시지 템플릿

위 지침을 충실히 따르는 예시 커밋 메시지 템플릿은 다음과 같습니다. (템플릿 적용 방법 가이드):

# (만약 적용된다면, 이 커밋은...) <제목>        (최대 72자)
# |<----          최대 72자로 사용하는 것을 권장합니다.                ---->|


# 이 변경 사항이 왜 이루어졌는지 설명하세요
# |<----   각 줄의 길이는 최대 72자로 제한됩니다.   ---->|


# 관련된 티켓, 문서 또는 다른 자원에 대한 링크 또는 키 제공
# 사용되지 않는다면 이슈와 Merge Request의 전체 URL을 사용하여 알기 쉽게 평문으로 표시될 수 있도록 해주세요

# --- 커밋 종료 ---
# --------------------
# 기억해야 할 사항
#    제목 줄을 대문자로 작성하기
#    명령조를 사용하여 제목 행 작성하기
#    점으로 제목 행을 끝내지 않기
#    제목은 적어도 3개의 단어를 포함해야 함
#    본문과 제목을 빈 줄로 구분하기
#    적어도 3개의 파일에서 30줄 이상의 변경을 하는 커밋은 이러한 변경 사항에 대해 본문에 설명해야 함
#    이모지를 사용하지 않기
#    본문에 어떻게나 왜를 설명하는 데 본문을 사용하기     
#    디렉터리에서 타이틀을 위해 "-"를 사용하여 여러 줄 사용하기
#    더 많은 정보: https://cbea.ms/git-commit/
# --------------------

기여 수락 기준

Merge Request이 승인될 수 있도록 하려면 아래의 기여 수락 기준을 충족시켜야 합니다.

변경 사항을 최소화합니다.
Merge Request에 500개 이상의 변경 사항이 포함된 경우:
- 이유를 설명합니다.
- 유지보수자를 언급합니다.
주요한 중단 변경 사항을 언급합니다.
적절한 테스트를 포함하고 모든 테스트를 통과하도록 합니다 (기존 코드의 버그를 드러내는 테스트가 포함된 경우에는 예외). 새로운 클래스마다 해당하는 단위 테스트를 작성해야 하며 해당 클래스가 상위 수준에서 실행되더라도 단위 테스트를 작성합니다.
- 실패한 CI 빌드가 기여와 무관한 것으로 보이면 실패한 CI 작업을 다시 시작하거나 실패를 해결할 수 있는 업데이트를 가져오기 위해 대상 브랜치 위에 재베이스하거나, 아직 해결되지 않은 경우 개발자에게 도움을 요청할 수 있습니다.
MR에 몇 가지 논리적으로 구성된 커밋이 포함되어 있거나 커밋 squash가 활성화되어 있는 경우.
변경 사항이 문제없이 Merge될 수 있어야 합니다. 그렇지 않을 경우 기능 브랜치에서 작업 중인 경우 리베이스하고, 그 외의 경우 기본 브랜치를 MR 브랜치에 Merge해야 합니다.
하나의 구체적인 문제가 수정되거나 특정한 기능이 구현되어야 합니다. 여러 가지를 결합하지 말고 각 문제 또는 기능에 대해 별도의 Merge Request을 보내야 합니다.
마이그레이션은 재시도를 용이하게 하기 위해 하나의 작업만 수행해야 합니다 (예: 테이블 생성, 데이터를 새로운 테이블로 이동, 또는 이전 테이블 제거).
다른 사용자가 혜택을 받을 수 있는 기능을 포함해야 합니다.
나중에 변경사항을 만들고 테스트하기를 복잡하게 하는 설정 옵션 또는 구성 옵션을 추가하지 말아야 합니다.
성능을 저하시키는 변경을 하지 말아야 합니다:
- 상당한 오버헤드를 필요로 하는 엔드포인트를 반복해서 폴링하는 것을 피합니다.
- SQL 로그 또는 QueryRecorder를 통해 N+1 쿼리를 확인합니다.
- 파일 시스템에 반복 액세스하는 것을 피합니다.
- 실시간 기능을 지원하기 위해 필요한 경우 ETag 캐싱과 폴링을 사용합니다.
Merge Request이 새로운 라이브러리(예: 젬 또는 JavaScript 라이브러리)를 추가하는 경우, 이들은 저희의 라이선싱 지침을 준수해야 합니다. “license-finder” 테스트가 Dependencies that need approval 오류로 실패하는 경우에는 해당 지침을 참조하여 도움을 받을 수 있습니다. 또한, 리뷰어에게 새로운 라이브러리에 대해 알리고 왜 필요한지 설명해야 합니다.
Merge Request이 GitLab 완료 정의를 충족해야 합니다.

완료 정의

GitLab에 기여하는 경우 변경 사항은 코드뿐만 아니라 더 많은 것을 포함합니다. 우리는 다음의 완료 정의를 사용합니다. 완료 정의에 도달하려면 Merge Request이 재현되어야 하고 모든 이러한 기준을 충족해야 합니다:

GitLab.com에서 프로덕션에서 동작함을 확인함.
Self-Managed 인스턴스에서 동작함을 확인함.
자체 서비스 프레임워크를 통해 Geo를 지원함. 자세한 정보는 Geo is a requirement in the definition of done을 참조하세요.

위반 사항이 발생하면 변경을 되돌리는 것을 선호합니다. 귀하의 기여는 이러한 모든 요구 사항을 충족하는지 확인할 때까지 불완전합니다.

기능

필요한 경우 주석이 달린 작동 및 깨끗한 코드.
변경 사항이 범위가 큰 작업의 영향을 제한하도록 평가됨.
성능 지침을 준수했음.
안전한 코딩 지침을 준수했음.
응용 프로그램 및 속도 제한 지침을 준수했음.
/doc 디렉터리에 문서화됨.
MR이 셸 명령을 실행하거나 파일을 읽거나 여는 코드를 다룰 때, 관련된 셸 명령 지침을 준수했음.
코드 변경에 대한 관찰 가능한 계측 기능이 포함되어 있음.
코드가 파일 저장을 다루어야 할 경우, 업로드 문서를 참조하세요.
여러 개의 마이그레이션을 추가하는 경우, MR이 검토되기 전에 신선한 데이터베이스에서 모든 마이그레이션을 실행함을 확인하세요. 검토 결과에 따라 MR에 큰 변경 사항이 발생하면 검토가 완료된 후 다시 마이그레이션을 실행하세요.
기존 모델에 새로운 유효성 검사를 추가하는 경우, 데이터 처리가 역호환성이 유지되도록 하기 위해:
- 기존 행에 영향을 미치지 않도록 확인하기 위해 #database Slack 채널에서 데이터베이스 쿼리를 실행하는 데 도움을 요청하세요.
- 변경사항을 점진적으로 배포하기 위한 피처 플래그와 함께 필요한 유효성 검사를 추가하세요. 배포 단계를 따르세요.
이 Merge Request이 긴급한 경우, 코드 소유자가 기존 행의 검토를 즉시 기본 작업으로 포함해야 할지에 대한 최종 결정을 내려야 합니다.

우리의 고객 데이터에 대한 정보를 알지 못하는 것은 없으므로 그러한 데이터가 있는 모든 자체 서비스 인스턴스에 대한 데이터 영향에 유의하세요.
자체 서비스 기능 및 업그레이드 경로를 고려하세요. 변경 사항은 다음을 고려해야 합니다.
- Self-Managed형를 위한 추가 작업이 필요한 경우, 그리고
- 변경 사항이 GitLab 버전을 업그레이드할 때 필수 중단이 필요한 경우.
업그레이드 중지는 때로는 GitLab 코드 변경이 백그라운드 마이그레이션이 이미 완료된 상황에 의존하는 경우에 요청됩니다. 가능하면, 업그레이드 중지를 일으키는 변경 사항은 다음 주요 릴리스나 불가피한 경우 최소한 3개 마일스톤의 사전 공지를 해야 합니다.

테스트

CI 서버에서 모든 단위, 통합 및 시스템 테스트를 통과함.
위험이 높은 변경에 대해 동료 구성원 테스트는 선택 사항이지만 권장됩니다. 이는 변경 사항이 넓은 영향을 미치거나 보안에 중요한 컴포넌트에 대한 경우에 해당합니다.
재발 및 버그는 문제가 다시 발생하는 위험을 감소시키는 테스트로 처리됨.
Capybara를 사용하는 테스트의 경우 신뢰할 수 있는 비동기 통합 테스트 작성 방법을 참고하세요.
필요한 경우 블랙 박스 테스트/엔드투엔드 테스트 추가. 질문이 있으면 품질 팀에 문의하세요.
가능한 경우 변경 사항이 검토 앱에서 테스트되어야 하고 적절한 경우 테스트해야 합니다.
피처 플래그로 영향을 받은 코드는 오토메이션된 테스트가 피처 플래그가 활성화된 상태와 비활성화된 상태에서 모두 통합되었거나, 혹은 둘 다 역할에 맞게 테스트되어야 합니다.
Merge Request이 하나 이상의 마이그레이션을 추가하는 경우, 보다 복잡한 마이그레이션을 위한 테스트를 작성하세요.

UI 변경사항

GitLab Design System, Pajamas에서 사용 가능한 컴포넌트 사용.
UI 변경이 이루어지면 Before와 After 스크린샷을 Merge Request(MR)에 포함해야 합니다.
MR이 CSS 클래스를 변경하는 경우, grep css-class ./app -R을 실행하여 영향을 받는 페이지 디렉터리을 포함해야 합니다.

변경 사항 설명

공헌의 관련성을 설명하는 명확한 제목과 설명.
리뷰어가 당신의 변경 사항을 볼 수 있도록 필요한 단계나 설정이 포함되어야 합니다(예: 피처 플래그와 관련된 정보 포함).
필요한 경우 변경 로그 항목 추가.
Merge Request이 소스에서 GitLab을 설치할 때 추가 단계가 필요한 변경 사항을 소개하는 경우, 동일한 Merge Request에서 doc/install/installation.md에 추가해야 합니다.
Merge Request이 소스에서 GitLab을 업그레이드할 때 추가 단계가 필요한 변경 사항을 소개하는 경우, 동일한 Merge Request에서 doc/update/upgrading_from_source.md에 추가해야 합니다. 이러한 지침이 특정 버전에 해당하는 경우, “특정 버전 업그레이드 지침” 섹션에 추가해야 합니다.

승인

Merge Request이 MR 수락 체크리스트에 따라 평가되었습니다.
관련성 부서에게 기본 설정을 변경하거나 새 설정을 도입하는 경우, 인프라 이슈 트래커에 이슈 생성해야 합니다.
합의된 롤아웃 계획을 만들어야 합니다.
관련 리뷰어에 의해 검토되었으며 가용성, 회귀 및 보안에 대한 모든 우려사항이 해결되었습니다. 문서 검토는 가능한 한 빨리 진행되어야 하지만 Merge Request을 차단해서는 안 됩니다.
Merge Request에는 적어도 1개의 승인이 있어야 하지만, 변경 내용에 따라 추가적인 승인이 필요할 수 있습니다. 승인 지침을 참조하세요.
- 특정 승인자를 선택할 필요는 없지만, Merge Request을 특정 사람이 승인하길 원하는 경우 선택할 수 있습니다.
프로젝트 관리자에 의해 Merge되었습니다.

실사용

Merge Request이 Merge된 후 다음 사항을 확인합니다:

가능한 경우 실사용에서 변경을 구현하기 전에 스테이징에서 작동하는지 확인되었습니다.
컨트리뷰션이 배포된 후 프로덕션에서 새로운 Sentry 오류가 발생하지 않고 작동하는지 확인했습니다.
롤아웃 계획이 완료되었는지 확인되었습니다.
변경 사항에 성능 리스크가 있는 경우, 변경 전후 시스템의 성능을 분석했는지 확인했습니다.
Merge Request이 피처 플래그, 프로젝트별 또는 그룹별 활성화 및 단계별 롤아웃을 사용하는 경우:
- GitLab 프로젝트에서 작동하는지 확인했습니다.
- 추가된 모든 프로젝트의 각 단계에서 작동하는지 확인했습니다.
관련이 있는 경우 릴리스 포스트에 추가했습니다.
관련이 있는 경우 웹사이트에 추가했습니다.

공헌에는 제품 팀의 승인이 필요하지 않습니다.

종속 항목

GitLab에 의존성을 추가하는 경우(예: 운영 체제 패키지), Merge Request에서 다음을 업데이트하고 각 항목의 적용성을 명시해야 합니다:

점진적 향상

우리는 엔지니어링 시간을 해결해야 할 작은 문제(이슈와 상관없이)에 할애하고 있습니다.

우선순위가 정해지지 않은 버그 수정(예: 프로젝트 이동 배너 경고가 모든 곳에 표시됨)
문서 개선
RuboCop 또는 코드 품질 개선

~"Stuff that should Just Work"를 통해 해당 영역의 작업을 추적하기 위해 Merge Request에 태그를 달아주세요.