병합 요청 워크플로우

우리는 GitLab 코드, 테스트 및 문서에 대한 수정 및 개선 사항을 가진 모든 사람들로부터의 병합 요청을 환영합니다. 커뮤니티 기여에 적합한 문제에는 커뮤니티 기여를 찾는 중 라벨이 있지만, 원하는 모든 문제에 대한 기여가 가능합니다.

문제로부터 작업하기

문제를 찾으면 가능하다면 수정 또는 개선 사항과 함께 병합 요청을 제출하고 테스트를 포함하세요.

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

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

GitLab 개발에 처음이라면(또는 웹 개발 전반에 처음이라면), 기여 방법 섹션에서 시작하는 것이 도움이 될 것입니다.

병합 요청 소유자

만일 문제가 현재 마일스톤에 지정된다면 언제든지, 작업 중인 경우에도 GitLab 팀 멤버가 릴리스 날짜 전에 작업이 완료될 수 있도록 병합 요청을 맡을 수 있습니다.

기여자가 제출한 병합 요청에 더 이상 적극적으로 작업하지 않는 경우, 우리는 다음을 할 수 있습니다:

병합 요청이 병합 요청 코치 중 한 명에 의해 완료될 것으로 결정합니다.
병합 요청을 닫습니다.

이 결정은 우리 제품 비전에 얼마나 중요한지에 기반합니다. 만일 병합 요청 코치가 병합 요청을 완료한다면, 우리는 ~coach will finish 레이블을 할당합니다.

팀 멤버가 커뮤니티 기여를 가져올 때, 우리는 원래 작성자를 변경로그 항목에 추가하여 크레딧을 주고, MR에서 적어도 하나의 커밋에 원래 작성자를 선택적으로 포함합니다.

기여자를 위한 병합 요청 가이드라인

기여 과정에 대한 안내를 보려면 튜토리얼: GitLab 기여하기를 참조하세요.

최선의 실천법

변경 사항이 복잡하다면, 제품 관리자 또는 팀 구성원과 토의하는 것을 장려합니다. 코드를 제출하기 전에 MR에서 그들을 태그하여 대화를 시작할 수 있습니다. 디자인 결정을 내릴 때 팀 멤버와 대화하는 것은 도움이 될 수 있습니다. 변경 사항 뒤에 깔린 의도를 전달하는 것도 병합 요청 검토를 신속히 도울 수 있습니다.
제품의 가용성에 영향을 줄 것으로 생각된다면 코드를 기능 플래그 뒤에 배치하는 것을 고려해보세요. 장담할 수 없다면, 기능 플래그 사용 시기를 읽어보세요.
병합 요청에 대한 신속한 피드백이 필요하다면, 코어 팀이나 병합 요청 코치 중 한 명을 언급하세요. 코드 검토를 받을 때와 병합 요청을 검토할 때는 코드 검토 가이드라인을 염두에 두세요. 그리고 만일 여러분의 코드가 데이터베이스에 변경 사항을 가한다면, 또는 비용이 많이 드는 쿼리를 실행한다면, 데이터베이스 검토 가이드라인을 확인하세요.

간단하게 유지하세요

작은 반복으로 생활하세요. 단일 MR 내에서의 변경 사항의 양을 가능한 한 작게 유지하는 것을 장려합니다. 큰 기능을 기여하려면, 최소 유효한 변경에 대해 신중히 생각해보세요. 기능을 두 개의 작은 MR로 나눌 수 있을까요? 백엔드/API 코드만 제출할 수 있을까요? 매우 간단한 UI로 시작할 수 있을까요? 리팩터의 일부분만 할 수 있을까요?

쉽게 검토될 수 있는 작은 MR은 GitLab에게 중요한 높은 코드 품질에 가깝습니다. MR이 작을수록, 빠르게 합병될 가능성이 높습니다. 그 후에, 더 많은 MR을 보내어 기능을 향상하고 확장할 수 있습니다. Kubernetes 팀의 더 빠른 PR 검토를 받는 방법 문서도 이에 관한 매우 좋은 점을 가지고 있습니다.

커밋 메시지 가이드라인

커밋 메시지는 아래의 가이드라인을 따라야 하며, Chris Beams가 Git 커밋 메시지를 작성하는 방법에서 설명한 이유로: - 커밋 제목과 본문은 공백으로 분리되어야 합니다. - 커밋 제목은 대문자로 시작해야 합니다. - 커밋 제목은 72자를 넘어서는 안 됩니다. - 커밋 제목은 마침표로 끝나서는 안 됩니다. - 커밋 본문은 한 줄에 72자를 넘어서는 안 됩니다. - 커밋 제목 또는 본문에 이모지를 포함해서는 안 됩니다. - 3개 이상의 파일에서 30줄 이상을 변경하는 커밋은 변경사항을 커밋 본문에 설명해야 합니다. - 짧은 참조 대신, 문제, 마일스톤, 병합 요청의 전체 URL을 사용하여 표시해야 합니다. 이는 GitLab 외부에서 평문으로 표시되기 때문입니다. - 병합 요청에는 10개 이상의 커밋 메시지가 포함되어서는 안 됩니다. - 커밋 제목은 적어도 3개의 단어를 포함해야 합니다.

중요 사항: - 가이드라인을 따르지 않으면, MR이 위험 검사를 통과하지 못할 수 있습니다. - 만약 여러분의 병합 요청이 “X 파일에 제안 적용” 커밋을 포함한다면, Squash and merge를 활성화할 수 있게끔 설정하면, Danger가 그것들을 무시하도록 할 수 있습니다. - [접두어] 형식의 커밋 메시지는 허용됩니다. (메시지 자체가 대문자인 한 모두 소문자로 작성할 수도 있습니다). 예를 들어, danger: Danger 동작 개선 및 [API] 레이블 엔드포인트 개선은 유효한 커밋 메시지입니다.

이러한 기준이 중요한 이유

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

커밋 메시지 템플릿

위의 내용을 반영하는 아래 예시 커밋 메시지 템플릿(템플릿 적용 방법 안내 링크 참조):

# (이 커밋이 적용되면...) <제목>        (최대 72자)
# |<----          72자 이내로 입력                ---->|


# 이 변경 내용이 왜 이루어졌는지 설명
# |<----   각 줄을 최대 72자로 제한하려고 노력   ---->|


# 관련 티켓, 문서 또는 다른 자료에 대한 링크 또는 키 제공
# 짧은 참조 대신 이슈 및 병합 요청의 전체 URL을 사용하여 텍스트로 표시되므로 해당 URL을 사용

# --- 커밋 종료 ---
# --------------------
# 기억해야 할 사항
#    제목 줄은 대문자로 시작
#    명령문 사용
#    제목 줄은 마침표 없이 끝내기
#    제목은 최소 3단어 이상
#    본문과 제목 사이에 빈 줄 삽입
#    3개 이상의 파일에서 30줄 이상의 변경이 있는 커밋에는
#    변경 내용을 커밋 본문에 설명
#    이모지 사용 금지
#    '어떻게'가 아닌 '무엇과 왜'에 대해 설명하기 위해 본문 사용
#    본문에 "-"를 사용하여 여러 줄로 나눠나가는 항목 사용 가능
#    추가 정보: https://cbea.ms/git-commit/
# --------------------

기여 수락 기준

병합 요청이 승인될 수 있는지 확인하려면 다음의 기여 수락 기준을 충족시켰는지 확인하세요:

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

완료 정의

만약 GitLab에 기여한다면, 변경 사항은 코드뿐만 아니라 더 많은 작업을 포함한다는 것을 알아야 합니다. 다음 완료 정의를 사용합니다. 완료 정의를 달성하려면 병합 요청은 재발생 현상을 만들지 않아야 하고 다음의 조건을 모두 충족해야 합니다:

GitLab.com에서 운영 환경에서 작동하는 것으로 확인됨.
자체 호스팅된 인스턴스에서 작동하는 것으로 확인됨.
자체 서비스 프레임워크를 통해 Geo를 지원함. 자세한 내용은 Geo가 완료 정의에 요구됨을 참조하세요.

재발생 현상이 발생하는 경우 변경 사항을 되돌리는 것이 우선입니다. 변경 사항이 모든 요구 사항을 충족하는지 확인해야만 기여가 완료됩니다.

기능

필요한 곳에 코멘트가 있는 작동 및 정돈된 코드.
변경이 첨단 작업의 영향을 제한하기 위해 평가됨.
성능 가이드라인을 준수함.
안전한 코딩 가이드라인을 준수함.
응용 프로그램 및 요율 제한 가이드라인을 준수함.
/doc 디렉토리에 문서화됨.
만약 MR이 쉘 명령어를 실행하거나 파일을 읽거나 열거나, 또는 디스크의 파일 경로를 다룬다면 해당하는 쉘 명령어 가이드라인을 준수하는지 확인하세요(shell command guidelines).
코드 변경에는 관측 가능성 계측을 포함해야 함(observability instrumentation).
코드가 파일 저장을 처리해야 하는 경우, 업로드 문서를 참조하세요.
만약 여러 마이그레이션을 추가하는 경우, MR이 검토되기 전에 모든 마이그레이션을 신선한 데이터베이스에서 실행해야 함. 검토가 MR에서 큰 변경으로 이끈다면, 검토가 완료된 후 마이그레이션을 다시 실행해야 함.
기존 모델에 새로운 유효성 검사를 추가하는 경우, 데이터 처리가 역방향 호환되도록 하기 위해:
- #database Slack 채널에서 기존 행을 확인하는 데이터베이스 쿼리 실행에 도움을 요청함으로써 기존 행이 변경되지 않도록 보장할 수 있음.
- 기능 플래그가 있는 필요한 유효성 검사를 추가하여 출시 단계를 따라 점진적으로 배포될 수 있도록 함.
이 MR이 긴급하다면, 코드 소유자가 기존 행을 검토하는 것이 MR의 즉각적인 후속 작업으로 포함되어야 하는지에 대한 최종 판단을 내려야 함.
참고: 고객의 데이터에 대해 자체 관리형 인스턴스에서는 아무것도 알 수 있는 방법이 없으므로 MR과 관련하여 데이터 영향에 대해 고려할 때 주의해야 함.
자체 관리 기능과 업그레이드 경로를 고려할 것. 변경 사항은 두 가지를 모두 고려해야 함:
- 자체 관리용 가용성에 대해 추가 작업이 필요한 경우, 및
- 변경 사항이 GitLab 버전을 업그레이드하는 데 필요한 중지가 필요한 경우.
업그레이드 중지가 때때로 GitLab 코드 변경이 백그라운드 마이그레이션이 이미 완료되어 있을 때에 의존적인 경우에 요청됨. 필수 업그레이드 중지를 유발하는 변경 사항은 이상적으로는 다음 주요 릴리스로 유보되어야 하거나 피할 수 없는 경우 최소 3개의 마일스톤 사전 공지를 해야 함.

테스트

CI 서버에서 모두 통과하는 단위, 통합 및 시스템 테스트.
변경의 위험이 클 때는 동료 구성원 테스트가 선택 사항이지만 권장됨. 이는 변경 사항이 첨단 작업의 영향을 제한하는 경우 또는 보안에 중요한 구성 요소에 대한 경우를 포함함.
테스트로 이슈가 다시 발생할 위험을 줄이는 테스트로 재현과 버그가 커버됨.
Capybara를 사용하는 테스트의 경우, 신뢰성 있는 비동기 통합 테스트 작성 방법을 참조하세요.
필요한 경우 블랙박스 테스트/종단 간 테스트 추가. 궁금한 사항이 있으면 품질 팀에 문의하세요.
가능하고 적절한 경우 리뷰 앱에서 변경 사항을 테스트함.
기능 플래그에 영향을 받는 코드는 자동화된 테스트로 기능 플래그를 활성화 및 비활성화된 상태로 테스트되거나 동료 구성원 테스트의 일부로 또는 롤아웃 계획의 일부로 두 가지 상태가 테스트되어야 함.
MR이 하나 이상의 마이그레이션을 추가하는 경우, 더 복잡한 마이그레이션을 위한 테스트를 작성함.

UI 변경

GitLab Design System, Pajamas에서 사용 가능한 구성 요소 사용.
MR에 만약 UI 변경이 있다면 이전 및 이후 스크린샷을 포함해야 함.
MR이 CSS 클래스를 변경하는 경우, grep css-class ./app -R을 실행하여 검색된 영향 받는 페이지 목록을 포함해야 함.

변경 내용 설명

해당 기여물의 중요성을 설명하는 명확한 제목과 설명.
리뷰어가 당신이 한 변경 사항을 볼 수 있도록 필요한 단계나 설정이 포함된 설명(예: 기능 플래그에 대한 정보 포함).
필요한 경우 Changelog 항목 추가.
만약 당신의 MR이 GitLab을 원본에서 설치하는 추가 단계를 필요로 하는 변경 사항을 제공한다면, 해당 MR에 doc/install/installation.md에 추가합니다.
만약 당신의 MR이 GitLab을 원본에서 업그레이드하는 추가 단계를 필요로 하는 변경 사항을 제공한다면, 해당 MR에 doc/update/upgrading_from_source.md에 추가합니다. 이러한 지침이 특정 버전에 해당하는 경우 “버전별 업그레이드 지침” 섹션에 추가합니다.

승인

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

운영 환경 사용

다음 항목은 MR이 병합된 후 체크됩니다:

실제 환경에서 변경을 구현하기 전에 스테이징에서 작동하는지 확인되었습니다.
기여가 배포된 후 샌트리 오류가 없는지 확인하였습니다.
롤아웃 계획이 완료되었는지 확인합니다.
변경 사항에 성능 위험이 있는 경우, 변경 전후로 시스템의 성능을 분석하였습니다.
만약 MR이 기능 플래그, 프로젝트별 또는 그룹별 활성화, 그리고 단계적 롤아웃을 사용하는 경우:
- GitLab 프로젝트에서 작동하는지 확인되었습니다.
- 추가된 모든 프로젝트의 각 단계에서 작동하는지 확인되었습니다.
관련이 있는 경우 릴리스 게시물에 추가되었습니다.
관련이 있는 경우 웹사이트에 추가되었습니다.

기여 사항은 제품 팀의 승인이 필요하지 않습니다.

종속성

GitLab에 의존성을 추가하는 경우(예: 운영 체제 패키지), 다음을 업데이트하고 당신의 MR에 각 항목의 적용 가능성을 기록해주세요:

릴리스 블로그 게시물에 추가를 기록합니다(없으면 생성).
업그레이드 가이드에 추가합니다.
GitLab 설치 가이드에 추가합니다.
GitLab 개발 키트를 업데이트합니다.
CI 환경 준비를 업데이트합니다.
옴니버스 패키지 생성기를 업데이트합니다.
Cloud Native GitLab Dockerfiles를 업데이트합니다.

점진적 개선

우리는 작은 문제를 해결하기 위해 엔지니어링 시간을 허용합니다(이슈와 상관없이), 다음과 같은 점진적 개선 사항에 대하여:

우선순위를 매기지 않은 버그 수정(예: 프로젝트 이동 알림 배너가 어디서나 표시됨).
문서 개선
RuboCop 또는 코드 품질 개선

단순히 작동해야 할 것들(~"Just Work가 되어야 할 것들"로 태그가 지정됨)을 추적하기 위해 MR에 태그를 지정해주세요.