Merge Request 워크플로우

우리는 GitLab 코드, 테스트, 그리고 문서를 개선하고 수정하는 모든 사람으로부터의 Merge Request을 환영합니다. 커뮤니티 기여에 적합한 문제는 커뮤니티 기여자용 레이블이 지정된 문제입니다만, 원하는 어떤 문제에도 기여할 수 있습니다.

문제에서 작업하기

문제를 찾았다면 가능하다면 수정 또는 개선사항이 있는 Merge Request을 제출하세요. 그리고 테스트를 포함하세요.

레이블이 지정되지 않은 새로운 기능을 추가하려면, 먼저 문제를 생성하고(이미 있는 경우 제외) 커뮤니티 기여자용 레이블로 지정되도록 요청하는 의견을 남기는 것이 가장 좋습니다. 기능 제안 섹션을 참조하세요.

문제를 해결하는 방법을 모르더라도 문제를 드러내는 테스트를 작성할 수 있다면, 그것도 우리는 받아들일 것입니다. 일반적으로, 회귀 테스트를 포함한 버그 수정은 신속하게 Merge됩니다. 적절한 테스트 없이 새로운 기능은 피드백을 받는 데 더 느릴 수 있습니다.

GitLab 개발에 처음이거나(web 개발 포함), 잠재적으로 쉬운 문제로 시작하려면 기여하는 방법 섹션을 참조하세요.

Merge Request 소유권

문제가 현재 마일스톤에 지정된 경우, 심지어 작업 중일 때에도 GitLab 팀원이 해당 문제를 마감일 전에 완료하도록 Merge Request을 맡을 수 있습니다.

기여자가 제출한 Merge Request을 더 이상 활발하게 진행하지 않는 경우, 우리는 다음과 같이 할 수 있습니다:

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

이 결정은 제품 비전에 대한 변경 사항의 중요성에 기반합니다. 만약 Merge Request 코치가 Merge Request을 완료하는 경우, 우리는 ~coach will finish 레이블을 지정합니다.

팀원이 커뮤니티 기여를 맡게 되면, 우리는 기존 작성자에게 크레딧을 주기 위해 변경 로그 항목에 작성자를 기재하고, 선택적으로 기존 작성자를 적어도 하나의 커밋에 포함시킵니다.

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

기여 프로세스에 대한 안내를 원하시면 튜토리얼: GitLab 기여하기를 참조하세요.

최고의 실천법

  • 변경 사항이 중요하지 않은 경우, 제품 매니저 또는 팀 구성원과 토론을 시작하는 것을 권장합니다. 코드를 제출하기 전에 MR에서 그들을 태깅해서 이렇게 할 수 있습니다. 팀 구성원과 대화하는 것은 디자인 결정을 내릴 때 도움이 될 수 있습니다. 변경 내용의 의도를 전달하는 것은 Merge Request 검토를 빠르게 하는 데 도움이 될 수 있습니다.

  • 프로덕션 가용성에 영향을 줄 것으로 생각된다면 코드를 피처 플래그 뒤에 넣는 것을 고려하세요. 자세한 내용은 피처 플래그 사용 시기를 참조하세요.

  • Merge Request에 대한 신속한 피드백을 받고 싶다면 코어 팀 또는 Merge Request 코치 중 한 명을 멘션해주세요. 코드 검토 시에는 코드 검토 가이드라인을 염두에 두고, 코드를 검토할 때와 Merge Request을 검토할 때, 데이터베이스 검토 가이드라인을 확인해주세요.

단순하게 유지하세요

작은 반복으로 사세요. 단일 Merge Request에 변경 사항의 양을 가능한 한 최소화하세요. 큰 기능을 기여하려면, 최소한의 변경 작업(MVC)이 무엇인지 신중하게 고려해보세요. 기능을 두 개의 더 작은 Merge Request으로 나눌 수 있을까요? 백엔드/API 코드만 제출할 수 있을까요? 매우 간단한 UI로 시작할 수 있을까요? 리팩터링의 일부만 할 수 있을까요?

작은 Merge Request은 더 쉽게 검토될 뿐만 아니라, GitLab에게는 최소한의 커밋 로그보다 더 중요한 더 높은 코드 품질을 가져다줍니다. Merge Request이 작을수록 더 빨리 Merge될 가능성이 높습니다. 그 후에 기능을 향상하고 확장하는 더 많은 Merge Request을 보낼 수 있습니다. Kubernetes 팀의 더 빠른 PR 검토 방법 문서에도 이에 관한 큰 많은 지점이 있습니다.

커밋 메시지 가이드라인

아래 가이드라인을 따르는 커밋 메시지는 Chris Beams가 설명한 이유에 따라야 합니다. How to Write a Git Commit Message를 참조하세요.

  • 커밋 제목과 본문은 빈 줄로 구분되어야 합니다.
  • 커밋 제목은 대문자로 시작해야 합니다.
  • 커밋 제목은 72자를 넘어서는 안 됩니다.
  • 커밋 제목은 마침표로 끝나서는 안 됩니다.
  • 커밋 본문의 각 줄은 72자를 넘어서는 안 됩니다.
  • 커밋 제목이나 본문에 이모지가 들어가서는 안 됩니다.
  • 3개 이상의 파일에서 최소 30줄 이상의 변경이 있는 커밋은 이러한 변경 사항을 커밋 본문에 기술해야 합니다.
  • GitLab 외부에서 일반 텍스트로 표기되므로 이슈, 마일스톤, 그리고 Merge Request의 전체 URL을 사용해야합니다.
  • Merge Request에는 10개 이상의 커밋 메시지가 들어서는 안 됩니다.
  • 커밋 제목에는 적어도 3개의 단어가 있어야 합니다.

중요 사항:

  • 가이드라인을 준수하지 않았을 경우, MR이 Danger checks를 통과하지 못할 수 있습니다.
  • 만약 Merge Request에 “Applied suggestion to X files” 커밋이 포함되어 있다면 Squash and merge를 활성화하는 것을 고려해주세요. 그래야 Danger가 이를 무시할 수 있습니다.
  • [prefix] 및 prefix: 형식의 접두사는 허용됩니다(메시지 자체가 대문자인 한 모두 소문자로 표시될 수 있습니다). 예를 들어, danger: Improve Danger behavior와 [API] Improve the labels endpoint는 유효한 커밋 메시지입니다.

이러한 표준이 중요한 이유

  1. 이러한 가이드라인을 따르는 일관된 커밋 메시지는 기록을 더 가독성 있게 만듭니다.
  2. 간결하고 표준화된 커밋 메시지는 배포나 ~"마스터:broken"과 같은 중단 변경 사항을 빠르게 확인할 수 있게 도와줍니다.

커밋 메시지 템플릿

위의 예시를 포함하는 머신에서 사용할 수 있는 커밋 메시지 템플릿입니다(템플릿 적용 방법에 대한 안내 여기참조): 

# (만약 적용된다면, 이 커밋은...) <제목>        (최대 72자)
# |<----          72자 이내로 입력                ---->|


# 이 변경 사항이 왜 이루어지고 있는지 설명
# |<----   각 줄은 최대 72자로 제한해보세요   ---->| 

# 관련 티켓, 문서, 또는 다른 자료들에 대한 링크나 키 제공
# 단축 참조가 아닌 문제 및 Merge Request의 전체 URL을 사용하세요. 왜냐하면 GitLab 외부에서 일반 텍스트로 표시되기 때문입니다.

# --- 커밋 끝 ---
# --------------------
# 주의할 점
#    제목 줄 첫 글자 대문자로 시작
#    명령조를 사용하여 제목 작성
#    제목 끝에 점을 찍지 않음
#    제목은 적어도 3단어를 포함해야 함
#    제목과 몸체 사이에 빈 줄을 넣으세요
#    3개 이상의 파일에서 30줄 이상의 변경이 있는 경우에는, 변경 사항을 커밋 몸체에 설명해야 함
#    이모지 사용 금지
#    몸체에는 어떻게가 아닌 무엇을, 그리고 왜 하는지를 설명
#    몸체에는 항목화를 위해 "-"로 여러 줄 사용 가능
#    더 많은 정보: https://cbea.ms/git-commit/
# --------------------

기여 수락 기준

당신의 Merge Request이 승인될 수 있는지 확인하려면, 아래의 기여 수락 기준을 충족시켜야 합니다:

  1. 변경 사항은 최대한 작아야 합니다.
  2. Merge Request에 500건 이상의 변경 사항이 포함된 경우:
    • 그 이유를 설명
    • 유지자 명시
  3. 주요한 중단 변경 사항을 명시하세요.
  4. 적절한 테스트가 포함되어 테스트가 모두 통과해야 합니다 (기존 코드의 버그를 드러내는 테스트를 포함하는 경우를 제외합니다). 새로운 클래스는 해당하는 단위 테스트를 가져야 하며, 해당 클래스가 사용될 수 있을 경우에도 포함되어야 합니다.
    • 기여 사항이 아닌 것으로 보이는 실패한 CI 빌드는 실패한 CI 작업을 다시 시작하거나, 실패를 해결할 수 있는 업데이트를 가져오기 위해 대상 브랜치 위에 리베이스해볼 수 있습니다. 그리고 아직 해결되지 않은 경우 개발자에게 도움을 요청할 수 있습니다.
  5. MR에는 몇 개의 논리적으로 조직된 커밋이 포함되거나 커밋을 Merge해야 하는 경우가 있어야 합니다.
  6. 변경 사항이 문제없이 Merge될 수 있어야 합니다. 그렇지 않은 경우, 당신이 단독으로 기능 브랜치에서 작업 중인 경우 리베이스를 하거나, 그렇지 않으면 기본 브랜치를 MR 브랜치에 Merge하세요.
  7. 특정 문제 하나가 수정되었거나, 특정 기능 하나가 구현되어야 합니다. 여러 가지를 결합하지 말고, 각 문제 또는 기능에 대해 별도의 Merge Request을 보내세요.
  8. 마이그레이션은 장애 발생 시 재시도를 돕기 위해 하나의 일만 수행해야 합니다 (예: 테이블 생성, 데이터를 새로운 테이블로 이동, 오래된 테이블 제거).
  9. 다른 사용자가 이점을 얻을 수 있는 기능을 포함합니다.
  10. 변경 사항이 미래 변경 사항의 프로덕션 및 테스트를 복잡하게 만드는 설정 옵션을 추가하지 마세요.
  11. 변경 사항이 성능을 저하시키지 않아야 합니다:
    • 상당한 오버헤드를 필요로 하는 엔드포인트를 반복해서 폴링하지 않도록 하세요.
    • SQL 로그 또는 QueryRecorder를 통해 N+1 쿼리를 확인하세요.
    • 파일 시스템을 반복해서 접근하지 않도록 하세요.
    • 실시간 기능을 지원하기 위한 필요에 따라 ETag 캐싱과 폴링을 사용하세요.
  12. 만약 Merge Request이 새로운 라이브러리(예: 지음 또는 JavaScript 라이브러리)를 추가하는 경우, 해당 라이브러리가 라이선스 지침을 준수해야 합니다. “license-finder” 테스트가 Dependencies that need approval 오류로 실패하는 경우, 해당 지침에 따라 새로운 라이브러리에 대해 리뷰어를 인식시키고 그 이유를 설명하세요.
  13. Merge Request이 GitLab의 완료 정의를 충족해야 합니다.

완료 정의

GitLab에 기여하는 경우, 코드 이외의 사항도 포함합니다. 우리는 다음 완료 정의를 사용합니다. 완료 정의를 충족하려면, Merge Request이 회귀를 일으키지 않고 다음 기준을 모두 충족하는지 확인해야 합니다:

회귀가 발생하는 경우, 변경 사항을 되돌리는 것이 우선입니다. 당신의 기여는 모든 이 요구 사항을 준수해야 불완전합니다.

기능

  1. 필요한 곳에 주석이 달린 작동하는 깨끗한 코드입니다.
  2. 넓게 영향을 끼칠 수 있는 작업의 영향을 줄이기 위한 평가가 이루어졌습니다.
  3. 성능 지침을 따랐습니다.
  4. 안전한 코딩 지침을 따랐습니다.
  5. 애플리케이션 및 속도 제한 지침을 따랐습니다.
  6. /doc 디렉터리에 문서화됐습니다.
  7. 당신의 MR이 쉘 명령 실행, 파일 읽기 또는 열기, 또는 디스크의 파일 경로를 다룰 경우, 쉘 명령 지침을 준수했는지 확인하세요
  8. 코드 변경에 관측 가능성 장치를 포함해야 합니다.
  9. 당신의 코드가 파일 리포지터리를 처리해야 하는 경우, 업로드 문서를 참조하세요.
  10. 당신의 Merge Request이 새로운 마이그레이션을 추가하는 경우, MR이 검토되기 전에 새로운 데이터베이스에 모든 마이그레이션을 실행해야 합니다. 검토 결과에 따라 MR의 변경 사항이 크게 변경된 경우, 검토가 완료된 후 다시 마이그레이션을 실행해야 합니다.
  11. 당신의 Merge Request이 기존 모델에 새로운 유효성 검증을 추가하는 경우, 데이터 처리가 역호환되게 되도록 기존 행에 영향을 주지 않는지 확인하기 위해 데이터베이스 쿼리를 실행하는 것을 도와줄 #database Slack 채널에서 도움을 요청하세요.
  12. 자세한 내용은 전개 절차를 따르기 위해 점진적으로 배포되도록 피처 플래그를 사용하도록 필요한 유효성 검사와 함께 추가하세요.

이 Merge Request이 긴급하다면, 코드 소유자는 기존 행을 검토하는 것이 즉각적인 후속 작업으로 포함해야 하는지에 대한 최종 결정을 내릴 것입니다.

note
당신의 수요자들의 데이터에 대해 어떠한 정보도 알 수 있는 방법이 없습니다. 그것은 당신의 Merge Request과 관련된 데이터 변화에 영향을 받을 수 있음을 염두에 두세요. 1. Self-managed 기능과 업그레이드 경로를 고려해야 합니다. 변경 사항은 다음을 고려해야 합니다:
  • Self-managed 가용성을 위해 추가적인 작업이 필요한 경우, 그리고
  • 변경 사항이 GitLab 버전을 업그레이드할 때 요구 중단이 필요한 경우.

업그레이드 중지는 때때로 GitLab 코드 변경이 배경 마이그레이션이 이미 완료되어야 하는 경우 요청됩니다. 이 경우, 요구 업그레이드 중지를 유지하는 변경 사항은 이번 주요 릴리스에 대기하거나 적어도 불가피한 경우에는 최소한 3개의 마일스톤 사전 공지를 요청해야 합니다.

테스트

  1. CI 서버에서 통과하는 단위, 통합 및 시스템 테스트를 수행합니다.
  2. 위험이 높을 때 동료 멤버 테스트는 선택 사항이지만 권장됩니다. 변경이 중대한 영향을 미칠 때 또는 보안에 중요한 컴포넌트에 대한 변경일 때 포함됩니다.
  3. 재발 및 버그가 다시 발생할 위험을 줄이는 테스트로 재현 및 버그를 처리합니다.
  4. Capybara를 사용하는 테스트의 경우, 신뢰할 수 있고 비동기적 통합 테스트 작성 방법을 읽어보세요.
  5. 필요한 경우 블랙박스 테스트/엔드 투 엔드 테스트를 추가합니다. 질문이 있으면 품질 팀에 문의하세요.
  6. 변경 사항이 가능하고 적절한 경우 리뷰 앱에서 테스트합니다.
  7. 피처 플래그에 영향을 받는 코드는 피처 플래그가 활성화되거나 비활성화된 자동화된 테스트와 함께 또는 이 두 가지 상태가 동료 멤버 테스트 또는 롤아웃 계획의 일부로 테스트됩니다.
  8. Merge Request이 하나 이상의 마이그레이션을 추가하는 경우, 더 복잡한 마이그레이션을 위한 테스트를 작성합니다.

UI 변경

  1. GitLab Design System, Pajamas에서 사용 가능한 컴포넌트를 사용합니다.
  2. UI 변경이 이루어진 경우 이전 및 이후 스크린샷을 포함해야 합니다.
  3. MR이 CSS 클래스를 변경하는 경우, 영향을 받는 페이지 디렉터리을 포함합니다. 이 디렉터리은 grep css-class ./app -R 명령을 통해 찾을 수 있습니다.

변경 사항 설명

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

승인

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

운영에 사용

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

  1. 변경 사항이 가능한 경우 스테이징에서 작동 여부를 확인합니다.
  2. 공헌이 배포된 후 프로덕션에서 Sentry 오류가 없는지 확인합니다.
  3. 롤아웃 계획이 완료되었는지 확인합니다.
  4. 변경 사항에 성능 리스크가 있는 경우, 변경 사항 적용 전후 시스템의 성능을 분석했는지 확인합니다.
  5. Merge Request이 피처 플래그, 프로젝트별 또는 그룹별 활성화, 단계별 롤아웃을 사용하는 경우:
    • GitLab 프로젝트에서 작동하는지 확인합니다.
    • 추가된 모든 프로젝트의 각 단계에서 작동하는지 확인합니다.
  6. 관련이 있다면 릴리스 게시물에 추가합니다.
  7. 관련이 있다면 웹사이트에 추가합니다.

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

의존성

GitLab에 의존성(예: 운영 체제 패키지)을 추가하는 경우 다음을 업데이트하고 Merge Request에 각 적용 가능성을 기재하세요.

  1. 릴리스 블로그 게시물에서 추가를 기록합니다(없는 경우 생성합니다).
  2. 업그레이드 가이드에 추가합니다.
  3. GitLab 설치 가이드에 추가합니다.
  4. GitLab 개발 키트를 추가합니다.
  5. CI 환경 준비를 업데이트합니다.
  6. Omnibus 패키지 생성기에서 업데이트합니다.
  7. Cloud Native GitLab Dockerfiles를 업데이트합니다.

점진적 개선

우리는 문제를 해결하기 위해 엔지니어링 시간을 허용합니다(문제가 있는 경우 또는 없는 경우에도). 이에는 다음과 같은 작은 개선이 포함됩니다:

  1. 우선순위가 정해지지 않은 버그 수정(예: 프로젝트 이동 배너 경고가 어디서나 표시됩니다)
  2. 문서 개선
  3. RuboCop 또는 코드 품질 개선

~"Stuff that should Just Work" 태그를 사용하여 작업을 추적합니다.

관련 주제