GitLab 코드, 테스트, 문서에 대한 수정과 개선이 담긴 머지 리퀘스트는 누구에게나 환영합니다. 커뮤니티 기여에 특히 적합한 이슈에는 다음 Seeking community contributions 레이블이 붙어 있지만, 원하는 어떤 이슈에든 기여할 수 있습니다.

이슈 기반 작업#

이슈를 발견했다면 가능한 범위에서 수정이나 개선을 담은 머지 리퀘스트를 제출하고, 테스트를 포함합니다.

레이블이 없는 새 기능을 추가하고 싶다면, 먼저 이슈를 만들고(이미 있다면 생략) Seeking community contributions 레이블을 붙여 달라는 댓글을 남기는 편이 좋습니다. 기능 제안 절을 참고합니다.

이슈를 고치는 방법은 모르지만 그 이슈를 드러내는 테스트를 작성할 수 있다면, 그것도 환영합니다. 일반적으로 회귀 테스트가 포함된 버그 수정은 빠르게 머지됩니다. 적절한 테스트가 없는 새 기능은 피드백을 받기까지 더 오래 걸릴 수 있습니다.

GitLab 개발(또는 웹 개발 전반)이 처음이라면 기여 방법 절을 참고해 비교적 쉬운 이슈부터 시작합니다.

머지 리퀘스트 소유권#

이슈가 현재 마일스톤으로 지정되면, 그 이슈를 작업하는 중이더라도 릴리스 날짜 전에 작업이 끝나도록 GitLab 팀원이 해당 머지 리퀘스트를 넘겨받을 수 있습니다.

제출된 머지 리퀘스트에 기여자가 더 이상 적극적으로 참여하지 않으면 GitLab은 다음과 같이 대응할 수 있습니다.

• 머지 리퀘스트 코치 중 한 명이 해당 머지 리퀘스트를 마무리하도록 결정합니다.
• 머지 리퀘스트를 닫습니다.

이 결정은 해당 변경이 GitLab 제품 비전에서 얼마나 중요한지를 기준으로 합니다. 머지 리퀘스트 코치가 머지 리퀘스트를 마무리하는 경우에는 ~coach will finish 레이블을 붙입니다.

팀원이 커뮤니티 기여를 이어받는 경우, 원저자를 명시한 변경 로그 항목을 추가해 기여를 밝히고, 필요하면 MR의 커밋 중 최소 하나에 원저자를 포함합니다.

기여자를 위한 머지 리퀘스트 가이드라인#

기여 절차를 처음부터 살펴보려면 튜토리얼: GitLab에 기여하기를 참고합니다.

모범 사례#

• 변경이 사소하지 않다면 제품 관리자나 팀 구성원과 논의를 시작하는 것을 권장합니다. 코드를 리뷰에 올리기 전에 MR에서 해당 인원을 태그하면 됩니다. 설계를 결정할 때 팀원과 이야기하면 도움이 됩니다. 변경의 의도를 함께 전달하면 머지 리퀘스트 리뷰도 빨라집니다.
• 프로덕션 가용성에 영향을 줄 수 있다고 판단되면 코드를 기능 플래그 뒤에 두는 방안을 검토합니다. 판단이 서지 않는다면 기능 플래그를 사용하는 시점을 참고합니다.
• 머지 리퀘스트에 대해 빠른 피드백을 받고 싶다면 코어 팀 구성원이나 머지 리퀘스트 코치를 멘션해도 됩니다. 코드를 리뷰받을 때와 머지 리퀘스트를 리뷰할 때는 코드 리뷰 가이드라인을 염두에 둡니다. 코드가 데이터베이스를 변경하거나 비용이 큰 쿼리를 실행한다면 데이터베이스 리뷰 가이드라인도 확인합니다.

단순하게 유지#

작은 단위로 반복합니다. 하나의 MR에 담기는 변경량을 최대한 작게 유지합니다. 큰 기능을 기여하려 한다면 최소 가치 변경이 무엇인지 깊이 고민합니다. 기능을 두 개의 작은 MR로 나눌 수 있는지, 백엔드·API 코드만 먼저 제출할 수 있는지, 아주 단순한 UI로 시작할 수 있는지, 리팩터링의 일부만 진행할 수 있는지 검토합니다.

작은 MR은 리뷰하기 쉬워 코드 품질을 높이며, GitLab에서는 커밋 로그를 최소로 유지하는 것보다 코드 품질이 더 중요합니다. MR 이 작을수록 빠르게 머지될 가능성이 높습니다. 그 뒤에 MR을 더 보내 기능을 개선하고 확장할 수 있습니다. Kubernetes 팀의 PR 리뷰를 더 빨리 받는 방법 문서에도 이와 관련한 유용한 내용이 있습니다.

커밋 메시지 가이드라인#

커밋 메시지는 아래 가이드라인을 따릅니다. 그 이유는 Chris Beams가 How to Write a Git Commit Message에서 설명합니다.

• 커밋 제목과 본문은 빈 줄로 구분합니다.
• 커밋 제목은 대문자로 시작합니다.
• 커밋 제목은 72자를 넘지 않습니다.
• 커밋 제목은 마침표로 끝내지 않습니다.
• 커밋 본문은 한 줄에 72자를 넘지 않습니다.
• 커밋 제목과 본문에는 이모지를 넣지 않습니다.
• 파일 3개 이상에서 30줄 이상을 변경하는 커밋은 그 변경 내용을 커밋 본문에 설명합니다.
• 이슈, 마일스톤, 머지 리퀘스트는 짧은 참조 대신 전체 URL을 사용합니다. GitLab 밖에서는 일반 텍스트로 표시되기 때문입니다.
• 머지 리퀘스트에 담기는 커밋 메시지는 10개를 넘지 않습니다. 작업이 논리적으로 구분되는 여러 부분에 걸쳐 있다면, 하나의 MR에 커밋을 많이 쌓기보다 스택 MR 사용을 검토합니다.
• 커밋 제목은 최소 세 단어로 작성합니다.

중요 사항:

• 가이드라인을 지키지 않으면 MR 이 Danger 검사를 통과하지 못할 수 있습니다.
• 머지 리퀘스트에 "Applied suggestion to X files" 커밋이 포함된다면, Danger가 해당 커밋을 무시하도록 Squash and merge 활성화를 검토합니다.
• [prefix] 및 prefix: 형태의 접두사는 허용됩니다(메시지 본문이 대문자로 시작하기만 하면 접두사는 모두 소문자여도 됩니다). 예를 들어 danger: Improve Danger behavior와 [API] Improve the labels endpoint는 올바른 커밋 메시지입니다.

이 기준이 중요한 이유#

1. 이 가이드라인을 따른 일관된 커밋 메시지는 히스토리를 읽기 쉽게 만듭니다.
2. 간결하고 표준화된 커밋 메시지는 두 시점 사이의 커밋을 검토할 때 배포에 영향을 주는 호환성 파괴 변경이나 ~"master:broken"을 더 빨리 찾아내는 데 도움이 됩니다.

커밋 메시지 템플릿#

위 내용을 반영해 로컬 머신에서 사용할 수 있는 커밋 메시지 템플릿 예시입니다(템플릿 적용 방법 안내).

# (If applied, this commit will...) <subject>        (Max 72 characters)
# |<----          Using a Maximum Of 72 Characters                ---->|

# Explain why this change is being made
# |<----   Try To Limit Each Line to a Maximum Of 72 Characters   ---->|

# Provide links or keys to any relevant tickets, articles or other resources
# Use issues and merge requests' full URLs instead of short references,
# as they are displayed as plain text outside of GitLab

# --- COMMIT END ---
# --------------------
# Remember to
#    Capitalize the subject line
#    Use the imperative mood in the subject line
#    Do not end the subject line with a period
#    Subject must contain at least 3 words
#    Separate subject from body with a blank line
#    Commits that change 30 or more lines across at least 3 files should
#    describe these changes in the commit body
#    Do not use Emojis
#    Use the body to explain what and why vs. how
#    Can use multiple lines with "-" for bullet points in body
#    For more information: https://cbea.ms/git-commit/
# --------------------

기여 수용 기준#

머지 리퀘스트가 승인될 수 있도록, 아래 기여 수용 기준을 충족하는지 확인합니다.

1. 변경이 가능한 한 작습니다.
2. 머지 리퀘스트에 500건이 넘는 변경이 포함된다면 다음과 같이 합니다.
   • 그 이유를 설명합니다
   • Maintainer를 멘션합니다
3. 주요 호환성 파괴 변경이 있다면 언급합니다.
4. 적절한 테스트를 포함하고 모든 테스트를 통과시킵니다(기존 코드의 버그를 드러내는 테스트가 포함된 경우는 예외입니다). 기능 테스트처럼 더 상위 수준에서 검증되더라도, 새로 만든 클래스에는 각각 대응하는 단위 테스트가 있어야 합니다.
   • CI 빌드 실패가 기여와 무관해 보인다면, 실패한 CI job을 다시 실행하거나 대상 브랜치 위로 리베이스해 실패를 해소할 수 있는 업데이트를 가져오거나, 아직 고쳐지지 않았다면 개발자에게 테스트 수정을 도와 달라고 요청할 수 있습니다.
5. MR에 논리적으로 정리된 소수의 커밋이 있거나 커밋 스쿼시가 활성화되어 있습니다. 리뷰 중에는 피드백에 따른 변경을 별도 커밋으로 푸시합니다. 머지 준비가 될 때까지 스쿼시하지 않습니다. MR diff 버전은 대안으로 삼기에 신뢰도가 낮습니다. 리베이스하면 깨지고(버전 diff에 피드백 반영분뿐 아니라 리베이스된 변경까지 포함됩니다), 실제 사용에서 부정확할 수 있습니다.
6. 변경이 문제 없이 머지됩니다. 그렇지 않다면 기능 브랜치에서 혼자 작업하는 경우에는 리베이스하고, 그 외의 경우에는 기본 브랜치를 MR 브랜치로 머지합니다.
7. 하나의 이슈만 수정하거나 하나의 기능만 구현합니다. 여러 가지를 한꺼번에 묶지 말고, 이슈나 기능마다 머지 리퀘스트를 따로 보냅니다.
8. 마이그레이션은 한 가지 일만 수행해(예: 테이블 생성, 새 테이블로 데이터 이동, 기존 테이블 제거) 실패 시 재시도가 쉬워야 합니다.
9. 다른 사용자에게도 도움이 되는 기능을 담습니다.
10. 이후 변경과 테스트를 복잡하게 만들므로 구성 옵션이나 설정 옵션을 추가하지 않습니다.
11. 변경이 성능을 떨어뜨리지 않습니다.
    • 부하가 큰 엔드포인트를 반복해서 폴링하지 않습니다.
    • SQL 로그나 QueryRecorder로 N+1 쿼리를 확인합니다.
    • 파일 시스템에 반복해서 접근하지 않습니다.
    • 실시간 기능을 지원해야 한다면 ETag 캐시를 사용한 폴링을 사용합니다.
12. 머지 리퀘스트가 새 라이브러리(gem 이나 JavaScript 라이브러리 등)를 추가한다면, 라이선스 가이드라인을 따라야 합니다. "license-finder" 테스트가 Dependencies that need approval 오류로 실패하면 해당 안내를 참고합니다. 또한 리뷰어에게 새 라이브러리를 알리고 필요한 이유를 설명합니다.
13. 머지 리퀘스트가 아래 GitLab 완료 정의를 충족합니다.

완료 정의#

GitLab에 기여할 때는 변경이 코드에만 국한되지 않는다는 점을 기억합니다. GitLab은 다음 완료 정의를 사용합니다. 완료 정의를 충족하려면 머지 리퀘스트가 회귀를 만들지 않고 다음 기준을 모두 충족해야 합니다.

• GitLab.com 프로덕션에서 동작이 검증되었습니다.

• GitLab Self-Managed / Dedicated 인스턴스에서 동작이 검증되었습니다.

• 셀프 서비스 프레임워크를 통해 Geo를 지원하는지 검증되었습니다. 자세한 내용은 Geo는 완료 정의의 요구 사항입니다를 참고합니다.

• GitLab.com에 영향을 주는 변경이라면 Cells 아키텍처와 호환되는지 검증되었습니다. 다음을 확인합니다.

  • 컴퓨트(웹 요청, Sidekiq 워커)는 단일 조직 범위로 한정되어야 합니다.
  • 고객에게 속한 새 데이터베이스 행에는 샤딩 키가 있어야 합니다.
  • 조직 외부에 고객 소유 리소스가 존재하지 않아야 합니다.
  • 조직 데이터는 다른 셀로 마이그레이션할 수 있어야 합니다.

  자세한 내용은 Cells 개발 원칙을 참고합니다.

회귀가 발생하면 변경을 되돌리는 방식을 권장합니다. 이 요구 사항을 모두 충족했는지 확인하기 전까지 기여는 완료된 것이 아닙니다.

기능#

1. 필요한 곳에 주석이 달린, 동작하는 깔끔한 코드입니다.

2. 광범위한 영향을 주는 작업의 파급을 제한하도록 변경을 평가했습니다.

3. 성능 가이드라인을 따랐습니다.

4. 보안 코딩 가이드라인을 따랐습니다.

5. 애플리케이션 및 속도 제한 가이드라인을 따랐습니다.

6. /doc 디렉터리에 문서화했습니다.

7. MR 이 셸 명령을 실행하거나 파일을 읽고 열거나 디스크의 파일 경로를 다루는 코드를 건드린다면, 셸 명령 가이드라인을 따르는지 확인합니다

8. 코드 변경에는 관측 계측을 포함합니다.

9. 코드에서 파일 스토리지를 다뤄야 한다면 업로드 문서를 참고합니다.

10. 머지 리퀘스트가 마이그레이션을 하나 이상 추가한다면, MR 리뷰 전에 새 데이터베이스에서 모든 마이그레이션을 실행합니다. 리뷰 결과 MR에 큰 변경이 생겼다면, 리뷰가 끝난 뒤 마이그레이션을 다시 실행합니다.

11. 머지 리퀘스트가 기존 모델에 새 검증을 추가한다면, 데이터 처리가 하위 호환되는지 확인합니다.

    • #database Slack 채널에 문의해 기존 행이 이 변경의 영향을 받지 않는지 확인하는 데이터베이스 쿼리를 실행하는 데 도움을 받습니다.
    • 롤아웃 단계에 따라 점진적으로 배포되도록 기능 플래그와 함께 필요한 검증을 추가합니다.

    이 머지 리퀘스트가 긴급하다면, 기존 행 검토를 머지 리퀘스트의 즉시 후속 작업으로 포함할지 여부는 코드 오너가 최종적으로 판단합니다.

    [!note] 고객의 GitLab Self-Managed 인스턴스에 있는 데이터는 전혀 알 수 없으므로, 머지 리퀘스트의 데이터 관련 영향을 판단할 때 이 점을 염두에 둡니다.

    1. self-managed 기능과 업그레이드 경로를 고려합니다. 변경은 다음 두 가지를 모두 고려해야 합니다.

    • self-managed 환경에서 사용할 수 있도록 추가 작업이 필요한지 여부
    • GitLab 버전을 업그레이드할 때 필수 정지가 필요한지 여부

    GitLab 코드 변경이 백그라운드 마이그레이션 완료에 의존하는 경우 업그레이드 정지를 요청하기도 합니다. 필수 업그레이드 정지를 유발하는 변경은 되도록 다음 메이저 릴리스로 미루거나, 불가피하다면 최소 3개 마일스톤 전에 공지하는 것이 바람직합니다.

테스트#

1. CI 서버에서 모두 통과하는 단위·통합·시스템 테스트가 있습니다.
2. 동료 구성원 테스트는 선택이지만 변경 위험이 높을 때는 권장합니다. 변경이 광범위한 영향을 미치거나 보안에 중요한 컴포넌트에 해당하는 경우가 여기에 속합니다.
3. 회귀와 버그는 같은 문제가 다시 발생할 위험을 줄이는 테스트로 커버합니다.
4. Capybara를 사용하는 테스트라면 신뢰할 수 있는 비동기 통합 테스트 작성법을 참고합니다.
5. 필요하다면 블랙박스 테스트·엔드 투 엔드 테스트를 추가합니다. 문의 사항은 품질 팀에 전달합니다.
6. 가능하고 적절한 경우 리뷰 앱에서 변경을 테스트합니다.
7. 기능 플래그의 영향을 받는 코드는 기능 플래그를 켠 상태와 끈 상태 모두에 대한 자동화 테스트로 커버하거나, 두 상태를 동료 구성원 테스트나 롤아웃 계획의 일부로 테스트합니다.
8. 머지 리퀘스트가 마이그레이션을 하나 이상 추가한다면, 복잡한 마이그레이션에는 테스트를 작성합니다.

UI 변경#

1. GitLab 디자인 시스템인 Pajamas에서 제공하는 컴포넌트를 사용합니다.
2. UI를 변경했다면 MR에 "Before" 와 "After" 스크린샷을 반드시 포함합니다.
3. MR 이 CSS 클래스를 변경한다면 영향을 받는 페이지 목록을 포함합니다. 이 목록은 grep css-class ./app -R을 실행해 확인할 수 있습니다.

변경 내용 설명#

1. 기여의 관련성을 설명하는 명확한 제목과 설명이 있습니다.
2. 리뷰어가 변경 내용을 확인할 수 있도록 필요한 단계나 설정을 설명에 포함합니다(예: 기능 플래그 관련 정보).
3. 필요하다면 변경 로그 항목을 추가했습니다.
4. 머지 리퀘스트가 GitLab을 직접 컴파일할 때 추가 단계가 필요한 변경을 도입한다면, 같은 머지 리퀘스트에서 doc/install/self_compiled/_index.md에 해당 단계를 추가합니다.
5. 머지 리퀘스트가 소스에서 GitLab을 업그레이드할 때 추가 단계가 필요한 변경을 도입한다면, 같은 머지 리퀘스트에서 doc/update/upgrading_from_source.md에 해당 단계를 추가합니다. 이 안내가 특정 버전에 한정된다면 "Version specific upgrading instructions" 절에 추가합니다.

승인#

1. MR을 MR 수용 체크리스트에 따라 평가했습니다.
2. 기여가 기본 설정을 변경하거나 새 설정을 도입한다면, 관련이 있는 경우 인프라 이슈 트래커에 이슈를 만들어 Infrastructure 부서에 알립니다.
3. 합의된 롤아웃 계획이 있습니다.
4. 관련 리뷰어가 리뷰했고 가용성·회귀·보안에 대한 우려가 모두 해소되었습니다. 문서 리뷰는 가능한 한 빨리 진행하되, 머지 리퀘스트를 막지는 않습니다.
5. 머지 리퀘스트에 승인이 최소 1건 있습니다. 다만 변경 내용에 따라 승인이 더 필요할 수 있습니다. 승인 가이드라인을 참고합니다.
   • 특정 승인자를 지정할 필요는 없지만, 특정 인원의 승인을 꼭 받고 싶다면 지정할 수 있습니다.
6. 프로젝트 Maintainer가 머지했습니다.

프로덕션 사용#

다음 항목은 머지 리퀘스트가 머지된 뒤에 확인합니다.

1. 가능한 경우 프로덕션에 변경을 적용하기 전에 스테이징에서 동작을 확인했습니다.
2. 기여가 배포된 뒤 새로운 Sentry 오류 없이 프로덕션에서 동작함을 확인했습니다.
3. 롤아웃 계획이 완료되었음을 확인했습니다.
4. 변경에 성능 위험이 있다면, 변경 전후의 시스템 성능을 분석했습니다.
5. 머지 리퀘스트가 기능 플래그, 프로젝트별·그룹별 활성화, 단계적 롤아웃을 사용하는 경우:
   • GitLab 프로젝트에서 동작을 확인했습니다.
   • 추가된 모든 프로젝트에 대해 각 단계에서 동작을 확인했습니다.
6. 관련이 있다면 릴리스 포스트에 추가했습니다.
7. 관련이 있다면 웹사이트에 추가했습니다.

기여에는 Product 팀의 승인이 필요하지 않습니다.

의존성#

GitLab에 의존성(운영 체제 패키지 등)을 추가한다면 다음 항목의 갱신을 검토하고, 각 항목의 해당 여부를 머지 리퀘스트에 기록합니다.

1. 릴리스 블로그 포스트에 추가 사실을 기록합니다 (아직 없다면 새로 만듭니다).
2. 업그레이드 가이드
3. GitLab 설치 가이드
4. GitLab Development Kit
5. CI 환경 준비
6. Linux 패키지 생성기
7. Cloud Native GitLab Dockerfile

점진적 개선#

GitLab은 이슈 유무와 관계없이 점진적 개선에 해당하는 작은 문제를 고칠 엔지니어링 시간을 허용합니다. 예를 들면 다음과 같습니다.

1. 우선순위가 지정되지 않은 버그 수정(예: 프로젝트 이동 알림 배너가 모든 화면에 표시되는 문제)
2. 문서 개선
3. RuboCop 또는 Code Quality 개선

이 영역의 작업을 추적하려면 머지 리퀘스트에 ~"Stuff that should Just Work" 태그를 붙입니다.

관련 주제#

• 머지 리퀘스트 작성자의 책임
• 머지 리퀘스트 리뷰 받기