병합 요청 워크플로우

우리는 GitLab 코드, 테스트 및 문서에 대한 수정 사항 및 개선 사항을 포함하여 누구에게나 병합 요청을 환영합니다. 커뮤니티 기여에 적합한 문제는 커뮤니티 기여를 찾습니다 라벨이 지정된 문제입니다만, 원하는 모든 문제에 기여할 수 있습니다.

문제에서 작업

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

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

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

GitLab 개발에 처음이라면(또는 웹 개발 전반에 처음이라면), 기여 방법 섹션을 참조하여 시작할 수 있습니다.

병합 요청 소유권

문제가 현재 마일스톤에 지정되어 있을 때 언제든지, 해당 문제를 작업 중이더라도 GitLab 팀원이 병합 요청을 가져와서 릴리스 날짜 전에 작업이 마무리되도록 할 수 있습니다.

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

  • 병합 요청 코치 중 한 명이 작업을 완료할 것으로 결정합니다.
  • 병합 요청을 닫습니다.

이 결정은 제품 비전에 변경 사항이 얼마나 중요한지에 따라 내립니다. 병합 요청 코치가 병합 요청을 완료할 예정이라면, 우리는 ~코치가 완료 레이블을 지정합니다.

팀원이 커뮤니티 기여를 받아들일 때, 우리는 원래 작성자를 인정하기 위해 변경 로그 항목을 추가하고 MR에서 적어도 하나의 커밋에 원래 작성자를 선택적으로 포함시킵니다.

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

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

최상의 실천 방법

  • 변경 사항이 복잡하다면, 코드를 리뷰하기 전에 제품 관리자 또는 팀원와 토론을 시작하는 것을 권장합니다. 코드를 제출하기 전에 MR에서 그들을 태그할 수 있습니다. 팀원과 대화하는 것은 설계 결정을 내릴 때 도움이 될 수 있습니다. 변경 사항의 의도를 전달하는 것도 병합 요청 리뷰를 신속하게 진행하는 데 도움이 될 수 있습니다.

  • 프로덕션 가용성에 영향을 줄 수 있다고 판단된다면 코드를 기능 플래그 뒤에 둘 것을 고려해보세요. 확실하지 않다면, 이 문서를 참조하세요.

  • 병합 요청에 대한 빠른 피드백을 원한다면 코어 팀 중 한 명이나 병합 요청 코치 중 한 명을 언급해도 괜찮습니다. 코드를 리뷰하거나 병합 요청을 리뷰할 때는 코드 리뷰 가이드라인을 염두에 두세요. 그리고 코드가 데이터베이스에 변경 사항을 가할 경우 또는 비용이 많이 드는 쿼리를 수행하는 경우, 데이터베이스 리뷰 가이드라인을 확인하세요.

간단히 하기

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

작은 MR은 더 쉽게 검토되며, GitLab에게 중요한 것은 최소한의 커밋 로그보다 더 높은 코드 품질이기 때문에, 좋은 코드 품질로 이루어진 작은 MR일수록 더 중요합니다. MR이 작을수록 해당 MR이 빨리 병합될 확률이 높습니다. 그 후 기능을 향상하고 확장하는 데 더 많은 MR을 보낼 수 있습니다. Kubernetes 팀의 PR 리뷰를 더 빨리 받는 방법 문서에도 이에 관한 좋은 지적이 있습니다.

커밋 메시지 가이드라인

커밋 메시지는 아래 지침을 따라야 합니다. 그 이유는 Chris Beams에 의해 Git 커밋 메시지 작성 방법에서 설명되어 있습니다:

  • 커밋 제목과 본문은 공백 한 줄로 구분되어야 합니다.
  • 커밋 제목은 대문자로 시작해야 합니다.
  • 커밋 제목은 72자를 넘어서는 안 됩니다.
  • 커밋 제목은 마침표로 끝나면 안 됩니다.
  • 커밋 본문은 한 줄당 72자를 넘어서는 안 됩니다.
  • 커밋 제목 또는 본문에 이모지가 들어가면 안 됩니다.
  • 3개 이상의 파일에서 30줄 이상 변경하는 경우, 이러한 변경 사항에 대해 설명해야 합니다.
  • 간결한 텍스트로 완전한 URL을 사용하세요.
  • 병합 요청에는 10개 이상의 커밋 메시지가 들어가면 안 됩니다.
  • 커밋 제목에는 적어도 3개의 단어가 포함되어야 합니다.

중요한 노트:

  • 지침을 따르지 않으면, MR이 Danger checks를 통과하지 못할 수 있습니다.
  • “Applied suggestion to X files” 커밋이 포함된 경우, Squash and merge를 사용하여 Danger가 해당 커밋을 무시할 수 있도록하는 것을 고려해보세요.
  • [prefix] 또는 prefix: 형식의 접두사는 허용됩니다 (메시지 자체가 대문자인 경우 소문자일 수 있습니다). 예를 들어, danger: Improve Danger behavior와 [API] 라벨 엔드포인트 향상은 유효한 커밋 메시지입니다.

이러한 표준의 중요성

  1. 이러한 지침을 준수하는 일관된 커밋 메시지는 히스토리를 더 읽기 쉽게 만듭니다.
  2. 간결하고 표준화된 커밋 메시지는 배포나 ~"master:broken"와 같은 중요한 변경 사항을 신속하게 식별할 수 있도록 도와줍니다.

커밋 메시지 템플릿

위 내용을 담은 예시 커밋 메시지 템플릿을 사용할 수 있습니다 (템플릿 적용 방법에 대한 안내): 

# (해당되는 경우 이 커밋은...) <제목>        (최대 72자)
# |<----          최대 72자를 사용하세요                ---->|


# 이 변경이 이루어지는 이유를 설명해주세요
# |<----   각 줄을 최대 72자로 제한하세요   ---->|

# 관련 티켓, 문서, 또는 다른 리소스에 대한 링크 또는 키 제공
# 짧은 참조 대신 이슈 및 병합 요청의 전체 URL을 사용하세요.
# GitLab 이외의 곳에서는 일반 텍스트로 표시되므로 짧은 참조 대신 전체 URL을 사용하세요.

# --- 커밋 끝 ---
# --------------------
# 다음 사항을 기억해주세요
#    제목 줄의 첫 글자는 대문자로 쓰세요
#    요구형이나 명령형으로 작성하세요
#    제목 줄을 마칠 때는 마침표를 찍지 마세요
#    제목은 최소 3단어를 포함해야 합니다
#    제목과 본문을 공백 한 줄로 구분하세요
#    3개 이상의 파일에서 30줄 이상의 변경이 있는 경우 이러한 변경 사항을 커밋 본문에 기술해야 합니다
#    이모지를 사용하지 마세요
#    본문을 사용하여 '무엇을'과 '왜'를 설명하세요
#    본문에서 글머리 기호('-')를 사용하여 여러 줄을 작성할 수 있습니다
#    자세한 내용은 다음 링크에서 확인하세요: https://cbea.ms/git-commit/
# --------------------

기여 수락 기준

병합 요청이 승인될 수 있는지 확인하려면 아래의 기여 수락 기준을 충족해야 합니다:

  1. 변경 사항이 가능한 한 작아야 합니다.
  2. 병합 요청에 500줄 이상의 변경 사항이 포함되어 있는 경우:
    • 그 이유를 설명해주세요
    • 유지보수자를 언급하세요
  3. 주요한 중단 변경 사항을 언급해주세요.
  4. 적절한 테스트를 포함하고 모든 테스트를 통과시켜주세요 (기존 코드의 버그를 드러내는 테스트를 제외하고). 모든 새로운 클래스는 관련 있는 테스트를 가져야 합니다. 해당 클래스가 특징 테스트와 같은 더 높은 수준에서 테스트되더라도 말이죠.
    • 기여에 관련이 없는 CI 빌드 실패라면 실패한 CI 작업을 다시 시작하거나 실패를 해결할 업데이트를 가져오기 위해 대상 브랜치 위에 리베이스하거나 아직 해결되지 않았다면 개발자에게 문의하여 테스트를 해결할 수 있습니다.
  5. 병합 요청이 논리적으로 구성된 몇 개의 커밋을 포함하거나 커밋 통합이 활성화되어 있는지 확인하세요.
  6. 변경 사항이 문제없이 병합될 수 있어야 합니다. 그렇지 않다면, 당신이 특정 기능 브랜치에서 작업하는 유일한 사람이라면 리베이스하고, 그렇지 않다면 기본 브랜치를 병합하여 MR 브랜치로 가져오세요.
  7. 고칠 문제 하나가 해결되거나 특정 기능이 구현되어져야 합니다. 여러 가지를 함께 병합 요청하지 말아주세요. 각 문제 또는 기능에 대해 별도의 병합 요청을 보내주세요.
  8. 마이그레이션은 실패를 재시도하기 용이하도록 한 가지 작업만 해야 합니다 (예: 테이블 생성, 데이터를 새로운 테이블로 이동 또는 이전 테이블 제거).
  9. 다른 사용자가 이점을 누릴 수 있는 기능을 포함해야 합니다.
  10. 변경 사항이 성능을 저하시키지 않아야 합니다:
    • 상당한 오버헤드가 필요한 엔드포인트의 반복된 폴링을 피해주세요.
    • SQL 로그 또는 QueryRecorder를 통해 N+1 쿼리를 확인해주세요.
    • 파일 시스템의 반복된 액세스를 피해주세요.
    • 실시간 기능을 지원하기 위해 필요한 경우 ETag 캐싱과 함께 폴링을 사용해주세요.
  11. 병합 요청이 새로운 라이브러리(예: gem 또는 JavaScript 라이브러리)를 추가하는 경우, 해당 라이브러리가 라이선스 지침을 준수해야 합니다. “라이선스 검색” 테스트가 Dependencies that need approval 오류와 함께 실패하는 경우 라이선스 지침을 확인하고, 새 라이브러리에 대해 리뷰어가 인식되도록 알려주고 필요성에 대해 설명해주세요.
  12. 병합 요청이 GitLab의 완료 정의를 충족해야 합니다.

완료 정의

만약 GitLab에 기여한다면, 변경 사항은 코드뿐만 아니라 더 많은 것을 포함한다는 것을 알아두세요. 우리는 다음 완료 정의를 사용합니다. 완료 정의에 도달하려면 병합 요청은 회귀가 없어야 하고 다음 모든 기준을 충족해야 합니다:

만약 회귀가 발생하면, 변경을 되돌리는 것을 선호합니다. 당신의 기여는 이러한 모든 요구 사항을 충족한다고 확신하게 될 때까지 불완전합니다.

기능

  1. 필요할 때 주석이 있는 작동 중인 깨끗한 코드
  2. 멀리 뻗어나가는 작업의 영향을 줄이기 위해 변경이 검토됨
  3. 성능 가이드라인을 따랐는지 확인함
  4. 보안 코딩 가이드라인을 따랐는지 확인함
  5. 응용 및 요금 제한 가이드라인을 따랐는지 확인함
  6. /doc 디렉토리에 문서화됨
  7. 만약 당신의 MR이 쉘 명령을 실행하거나 파일을 읽거나 열거나 디스크상의 파일 경로를 다루는 코드를 만지는 경우, 해당 코드가 쉘 명령 가이드라인을 따르는지 확인하세요
  8. 코드 변경 사항에 가시성 계측 장비를 포함함
  9. 당신의 코드가 파일 저장을 다루는 경우, 업로드 문서를 확인하세요
  10. 만약 당신의 병합 요청이 하나 이상의 마이그레이션을 추가한다면, MR이 검토되기 전에 신선한 데이터베이스에서 모든 마이그레이션을 실행해야 합니다. 만약 검토가 MR에 큰 변경 사항으로 이끈다면, MR 검토 이후에 마이그레이션을 다시 실행해야 합니다.

  11. 만약 당신의 병합 요청이 기존 모델에 새로운 유효성 검사를 추가한다면, 데이터 처리가 역호환성을 유지할 수 있도록하는데:

    • 이미 있는 행이 변화를 받지 않도록 하는 것입니다.
    • 변화에 따라 점진적으로 전개되는 특징 깃발을 가지고 필요한 유효성 검사를 추가하세요 전개 과정을 따르세요.

    만약 해당 병합 요청이 긴급하다면, 코드 소유자는 기존 행을 검토할 것인지를 최종적으로 결정해야 합니다. 이메일: 당신은 당신의 고객들의 Self-Managed 인스턴스에 대한 데이터에 대해 어떠한 정보도 알 수 있는 방법이 없습니다. 그것을 기억하세요.

  12. Self-Managed 기능과 업그레이드 경로를 고려하세요. 변경 사항은 다음 두 가지를 고려해야 합니다:

    • Self-Managed 가용성을 위해 추가적인 작업이 필요한지, 그리고
    • 변경이 GitLab 버전을 업그레이드할 때 필요한 중지가 필요한지

    업그레이드 중지는 때로는 배경 마이그레이션이 이미 완료되어야 하는 GitLab 코드 변경의 종속성에 따라 요청됩니다. 이러한 만약 피할 수 없다면, 적어도 미래의 변화에 대한 3개의 이정표 발표 앞에 또는 최소한 다음 주요 릴리스에 유지 중지를 요청하세요. 3개 이상의 이정표는 필수적인 업그레이드 중지를 요청할 때 요구됩니다.

테스팅

  1. CI 서버에서 모두 통과하는 단위, 통합 및 시스템 테스트.
  2. 위험한 변경의 경우 동료 멤버 테스트는 선택 사항이지만 권장됩니다. 이는 변경 사항이 범용적하거나 보안에 중요한 구성 요소에 대한 경우 등을 포함합니다.
  3. 문제 재발을 줄이는 테스트로 회귀 및 버그를 다룹니다.
  4. Capybara를 사용하는 테스트의 경우 신뢰할 수 있는 비동기 통합 테스트 작성 방법을 읽으세요.
  5. 필요한 경우 블랙박스 테스트/엔드 투 엔드 테스트를 추가합니다. 질문이 있으시면 품질 팀에 문의하세요.
  6. 변경 사항이 가능한 경우 검토 앱에서 테스트되며 적절한 경우입니다.
  7. 기능 플래그에 영향을 받는 코드는 기능 플래그가 활성화 및 비활성화된 자동화된 테스트로 다루거나 동료 멤버 테스트 또는 롤아웃 계획의 일부로 둘 다 테스트합니다.
  8. MR이 하나 이상의 마이그레이션을 추가하는 경우 더 복잡한 마이그레이션에 대한 테스트를 작성하세요.

UI 변경 사항

  1. GitLab Design System, Pajamas에서 사용 가능한 구성 요소를 사용합니다.
  2. MR은 UI 변경 사항이 있는 경우 Before 및 After 스크린샷을 포함해야 합니다.
  3. MR이 CSS 클래스를 변경하는 경우 영향을 받는 페이지 목록을 포함합니다. 이를 찾으려면 grep css-class ./app -R를 실행하세요.

변경 사항 설명

  1. 기여의 관련성을 설명하는 명확한 제목 및 설명을 사용합니다.
  2. 검토자가 당신의 변경 사항을 볼 수 있도록 필요한 단계 또는 설정을 설명에 포함합니다 (예: 기능 플래그에 대한 정보를 포함).
  3. 필요한 경우 변경 로그 항목 추가.
  4. 만약 MR이 소스에서 GitLab을 설치할 때 추가적인 단계를 요구하는 변경 사항을 도입하는 경우, MR에 해당 내용을 doc/install/installation.md에 추가합니다.
  5. MR이 소스에서 GitLab을 업그레이드할 때 추가적인 단계를 요구하는 변경 사항을 도입하는 경우, MR에 해당 내용을 doc/update/upgrading_from_source.md에 추가합니다. 이러한 지침이 특정 버전에 해당하는 경우, “특정 버전 업그레이드 지침” 섹션에 추가합니다.

승인

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

프로덕션 사용

MR이 병합된 후 다음 사항은 확인됩니다.

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

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

의존성

GitLab에 의존성을 추가하는 경우 (예: 운영 체제 패키지), 다음을 업데이트하는 것을 고려하고 MR 설명에서 각 항목의 적용 가능성을 주목하세요.

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

점진적 개선

우리는 엔지니어링 시간을 제공하여 작은 문제를 해결하는 것을 허용합니다 (이슈와 상관없이).

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

작업이 확인되었음을 추적하기 위해 MR에 ~"Stuff that should Just Work" 태그를 추가합니다.

관련 주제