머지 리퀘스트 검토는 고품질 코드만 코드베이스에 들어갈 수 있도록 보장합니다. 이 튜토리얼은 GitLab에서 머지 리퀘스트를 검토하는 방법을 보여줍니다. 머지 리퀘스트 자체의 구조와 건설적이고 도움이 되는 피드백을 제공하는 프로세스를 안내합니다. 튜토리얼이 끝나면 머지 리퀘스트를 승인하거나 추가 변경을 요청할 준비가 됩니다.

개요를 보려면 머지 리퀘스트 검토를 참조하세요.

머지 리퀘스트를 검토하려면:

1. 머지 리퀘스트로 이동
2. 머지 리퀘스트의 구조 이해
3. 높은 수준의 보기 얻기
   1. 관련 이슈 확인
   2. 사이드바 확인
   3. 댓글 확인
4. 코드 변경 사항 읽기
   1. 개요를 위한 변경 사항 훑어보기
   2. 각 파일을 심층적으로 검토
   3. 코드 테스트
   4. 파이프라인 확인
   5. 재검토 고려 사항
   6. 큰 그림 생각
5. 검토 완료
   1. 검토 댓글 작성
   2. 검토 요약
6. 정리 작업 수행

머지 리퀘스트로 이동#

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 다음 중 하나를 선택합니다:
   • Shift+r을 눌러 Merge requests 페이지로 이동합니다.
   • 오른쪽 상단에서 Merge requests([merge-request])를 선택합니다.

머지 리퀘스트의 구조 이해#

머지 리퀘스트에는 네 가지 옵션이 있는 보조 메뉴가 있습니다. 검토 중 다른 시점에 머지 리퀘스트의 이러한 영역을 사용합니다:

• Overview: 머지 리퀘스트의 설명, 현재 머지 가능성에 대한 보고서, 댓글이 있는 Activity 영역, 추가 정보가 있는 사이드바.
• Commits: 이 머지 리퀘스트의 커밋 목록, 최신 커밋 순서.
• Pipelines: 이 머지 리퀘스트의 내용에 대해 실행된 CI/CD 파이프라인 목록.
• Changes: 이 머지 리퀘스트에서 제안된 변경 사항의 diff, 제거, 추가 및 변경된 줄 표시.

Overview 탭의 사이드바에는 머지 리퀘스트 자체에 대한 중요한 메타데이터가 포함됩니다: 담당자, 검토자, 레이블, 마일스톤 및 시간 추적.

머지 리퀘스트의 높은 수준 보기 얻기#

코드 검토에 뛰어들기 전에 높은 수준에서 머지 리퀘스트를 평가해야 합니다. 머지 리퀘스트의 맥락과 목적을 이해합니다: 무엇을 하려는지, 왜 그러는지. 다음 질문을 스스로에게 물어보면서 해당 요구 사항을 여러분의 기술 세트와 비교합니다:

1. 머지 리퀘스트 뒤의 이야기는 무엇인가? 이 영역에서 사려 깊은 검토를 수행하기에 충분한 배경 지식이 있는가?
2. 어떤 유형과 깊이의 검토가 요청되었는가? 예를 들어, 좁은 범위의 버그 수정과 심층적인 아키텍처 검토는 매우 다른 검토 기대치를 가질 가능성이 있습니다.
3. 이 작업을 검토하기에 적합한 사람인가? 필요한 검토 유형이 여러분의 기술과 능력과 일치하는가?

머지 리퀘스트의 설명을 먼저 살펴보는 것으로 시작합니다. 이슈의 문제나 기능 요청에 대한 해결책이어야 합니다.

• 작성자는 누구인가? 이 사람의 작업에 익숙한가? 익숙하다면 일반적으로 코드베이스의 어느 부분에서 작업하는가? 나중에 작성자에 대한 지식이 변경 사항을 얼마나 면밀히 검토할지 판단하는 데 도움이 됩니다.
• 목표는 무엇인가? 작성자의 의도를 이해하기 위해 설명을 읽습니다.
• 초안인가? 초안은 종종 불완전하거나 이론적인 해결책입니다. 초안 머지 리퀘스트는 완전히 완성된 머지 리퀘스트와 다른 수준의 면밀한 검토가 필요할 수 있습니다.
• 문제를 어떻게 재현할 수 있는가? 설명이 문제를 재현하거나, 변경 사항을 테스트하거나, 새 기능을 시도하는 방법을 설명하는가? 안내를 위한 스크린샷이 포함되어 있는가?

설명 아래에서 머지 리퀘스트 위젯을 확인하여 이 작업의 현재 상태를 이해합니다. 이 예제는 승인이 누락되고, 여전히 초안 모드이며, 열린 토론 스레드가 있는 머지 리퀘스트의 머지 위젯을 보여줍니다:

• 이슈에 교차 링크가 있는가? 다른 이슈에 대한 링크는 설명과 머지 위젯에서 확인합니다. 일부 머지 리퀘스트는 간단하지만, 일부는 이 머지 리퀘스트가 어떻게 생성되었는지 이해하기 위해 해당 이슈를 읽어야 합니다. 더 복잡한 머지 리퀘스트는 전체 정보가 있는 이슈를 가리켜야 합니다.
• 파이프라인 상태는 무엇인가? 파이프라인이 녹색인가? 빨간 파이프라인은 문제를 가리킵니다. 불완전하거나 취소된 파이프라인이 보이면 작업의 전체 머지 가능성을 아직 평가할 수 없습니다.

관련 이슈 확인#

관련 이슈가 있고 더 많은 정보가 필요할 만큼 머지 리퀘스트가 복잡하다고 느껴지면 이슈 설명을 훑어봅니다.

• 문제와 해결책이 분리되어 있는가? 이슈는 문제를 설명하고 조사해야 하며, 머지 리퀘스트는 해결책에 초점을 맞춰야 합니다.
• 머지 리퀘스트 작성자가 이슈에 관여했는가? 검토 과정 전체에서 문제(또는 기능)를 정의하는 데 도움을 준 사람들을 생각해 봅니다. 이상적으로는 이러한 사람들도 머지 리퀘스트에 관여해야 합니다.

사이드바 확인#

• 어떤 레이블이 있는가? 레이블은 머지 리퀘스트의 내용에 대한 단서를 제공할 수 있습니다. 팀의 워크플로에 따라 불완전하거나 누락된 레이블은 무해할 수도 있고, 또는 이 머지 리퀘스트에 전체 정보가 부족하다는 것을 나타낼 수도 있습니다.

  • 레이블이 전문 분야와 일치하면 이 머지 리퀘스트를 검토하기에 적합한 후보일 가능성이 있습니다.
  • 레이블이 없는 전문 분야와 일치하면 머지 리퀘스트를 다른 검토자에게 재할당해야 할 수 있습니다.
  • 워크플로에서 기대하는 레이블을 추가합니다.

  이 예제에서 정확한 레이블을 모르더라도 이 머지 리퀘스트가 데이터베이스 버그에 관한 것임을 판단할 수 있습니다:

  

• 검토자는 누구인가? 검토자 목록의 이름을 훑어봅니다. 설명과 (선택적으로) 레이블을 기반으로 예상되는 작업 유형과 일치하는가? 존재하는 사람과 부재한 사람 모두를 고려합니다. 이 이름들이 머지 리퀘스트가 검토 사이클에서 어디에 있는지에 대해 무엇을 말해주는가? 누군가를 추가하거나 제거해야 하는가?

• 이미 승인한 검토자가 있는가? 해당 검토자와 전문 분야를 알고 있다면 제안된 변경 사항에서 어느 부분에 주의가 필요한지 어느 정도 파악할 수 있습니다.

  이 예제에서 Thomas와 Nick 모두 검토자입니다. Thomas는 아직 머지 리퀘스트를 검토([dotted-circle])하지 않았습니다. Nick은 검토하고 승인([check-circle])했습니다:

  

댓글 확인#

Overview 페이지에서 작성자와 다른 사람들이 남긴 댓글을 읽습니다. 코드 변경 사항을 읽을 때 그 토론들을 염두에 둡니다.

댓글에서 이전 검토의 흔적이 있는가? 많은 수의 댓글이 이 작업을 얼마나 심층적으로 검토할지에 영향을 줄 수 있습니다.

코드 변경 사항 읽기#

이제 제안된 변경 사항을 읽을 준비가 되었습니다. 대형 머지 리퀘스트의 경우 세부적으로 살펴보기 전에 변경 사항을 훑어봅니다. 줄별로 변경 사항을 읽기 시작하기 전에 무엇을 예상해야 할지에 대한 이해를 구축합니다.

개요를 위한 변경 사항 훑어보기#

Changes 페이지를 처음 열 때 먼저 더 넓은 세부 사항에 초점을 맞춥니다:

• 어떤 파일이 변경되었는가? 파일 브라우저([file-tree])를 확장하여 변경된 파일 목록을 봅니다. 이 파일들에 익숙한가? 코드베이스의 어느 부분에 있는 파일인가?

  

• 파일 목록이 예상과 일치하는가? 이미 머지 리퀘스트의 설명을 읽었습니다. 이러한 종류의 작업에 대해 예상되는 파일이 변경되었는가? 예상치 못한 파일의 변경 사항이나 예상되는 변경 사항이 누락된 경우 특별히 주의를 기울입니다.

• 추가, 제거 또는 변경된 줄이 있는가? 이 숫자는 더 깊이 읽을 때 어떤 종류의 작업을 예상해야 하는지 알려줍니다: 새 기능, 제거된 기능 또는 동작 변경?

• 어떤 테스트가 변경되었는가? 파일 중 일부가 테스트 스위트의 일부인가? 그렇지 않으면 작성자에게 테스트를 업데이트하도록 촉구해야 할 수 있습니다.

• 기능 플래그가 사용되었는가? 기능 플래그가 보이면 더 깊이 읽을 때 사용 여부를 확인하기 위해 메모합니다.

변경 사항을 훑어본 후 줄별로 변경 사항을 읽을 준비가 되었습니다!

각 파일을 심층적으로 검토#

이제 이 머지 리퀘스트에 포함된 변경 사항에 대한 넓은 아이디어가 생겼습니다. 변경 사항을 완전히 읽을 시간입니다. 지식이 강한 부분과 약한 부분을 인식합니다. 이 프로젝트를 잘 알고 있는가? 변경 사항이 익숙한 언어로 작성되었는가?

• 변경 사항이 명확하고 이해하기 쉬운가?
• 기능 플래그가 사용되었는가? 변경 사항이 기능 플래그의 존재 여부를 테스트하는가? 플래그가 비활성화되었을 때 기능 플래그가 적용된 변경 사항이 실수로 누출되지 않는지 확인합니다.
• 성능이 좋은가? 직접 성능을 테스트하는 데 편안한가, 아니면 더 심층적인 성능 지식을 가진 검토자를 추가해야 하는가?
• 단순화할 수 있는가?
• 엣지 케이스를 고려하는가?
• 올바르게 주석 처리되고 문서화되었는가? 좋은 코드는 작성자만이 아니라 다른 사람이 유지 관리할 수 있습니다. 작성자가 이 작업을 유지 관리할 수 있도록 충분한 설명을 제공했는가?
• 팀의 스타일 기대치를 따르는가?
• 하위 호환성이 있는가? 이 작업은 breaking change인가? 데이터 손실을 일으킬 수 있는가?
• 보안 우려 사항이 해결되었는가? 변경 사항이 프로젝트에서 특별한 보안 우려 사항이 있는 영역에 있는가? 민감한 데이터를 적절히 처리하는가? 사용자 입력을 받고 그것이 처리되었는가? 더 많은 보안 지식을 가진 검토자를 추가해야 하는가?
• 디버깅 구문이 남아 있는가?

변경 사항의 유형에 따라 코드베이스에 다른 영향을 미칩니다. 넓은 의미에서 고려합니다:

• 추가된 줄: 새 코드는 기존 동작을 수정해서는 안 됩니다. 새 동작이 테스트되었는가? 테스트가 충분히 세분화되었는가?
• 제거된 줄: 제거가 깔끔하고 완전한가? 제거된 코드와 테스트가 범위에서 서로 일치하는가? 어느 곳에도 부분적인 스텁이 남아 있지 않은지 확인합니다.
• 수정된 줄: 추가된 줄과 제거된 줄이 서로 대략 같다면, 변경 사항이 기존 코드의 리팩토링인가? 리팩토링의 경우, 이전 코드가 무엇을 했는지, 새 코드가 어떻게 다르게 하는지 이해하는가? 동작의 변경이 작성자의 설명에 명시된 의도와 일치하는가? 테스트가 여전히 제대로 작동하는가?

코드 테스트#

안타깝게도 여기서 많은 안내를 제공할 수 없습니다. 모든 프로젝트는 다릅니다! 애플리케이션을 직접 알지 못하면 변경 사항을 테스트하는 방법을 알려드릴 수 없지만, 고려해야 할 몇 가지 질문을 제공할 수 있습니다:

• 작동하는가? 겉보기에는 단순한 질문이지만 염두에 두는 것이 중요합니다. 코드는 못생기고, 복잡하고, 문서화되지 않을 수 있지만 여전히 작동합니다.

• 검토 프로세스가 얼마나 진행되었는가? 검토 과정의 초기인가 후기인가? 전문가인가?

  • 초기 검토자는 코드가 작성자가 말하는 방식으로 작동하는지 확인해야 합니다. 이는 머지할 수 없거나 머지해서는 안 되는 코드에 더 많은 사람이 시간을 쏟는 것을 방지합니다.
  • 후기 검토자는 기능이 광고된 대로 작동하는지 확인하는 데 관여하지 않을 수 있지만, 스타일과 유지 관리 가능성에 더 집중할 수 있습니다.
  • 전문 검토자는 전체 머지 리퀘스트가 예상대로 작동하는지 여부를 다루지 않고 머지 리퀘스트의 특정 부분만 검토할 수 있습니다.

코드를 테스트하는 동안 파이프라인 상태도 확인해야 합니다. 아직 검토 댓글을 작성하지 않았지만 거의 준비가 되었습니다.

파이프라인 확인#

머지 리퀘스트의 Pipelines 탭으로 이동하여 파이프라인 상태를 확인합니다. 파이프라인이 성공한 경우에만 머지 리퀘스트를 승인합니다. 이 예제에서는 여러 작업이 실패했습니다:

• 예상된 모든 테스트가 실행되었는가? 파이프라인이 녹색일 뿐만 아니라 완전한지 확인합니다.
• 실패한 테스트가 있는가? Failed jobs를 확장하여 어떤 테스트가 실패했는지 확인합니다.
• 각 실패한 작업에서 무슨 일이 있었는가? 실패한 각 작업을 선택합니다. 출력을 스크롤하면서 실패, 오류 및 빨간색으로 표시된 줄에 대한 언급을 스캔합니다. 검토 댓글을 작성할 때 작성자가 무엇을 수정해야 하는지, 어떻게 하는지 이해하도록 도와야 합니다.
• 실패가 변경 사항과 관련이 있는가? 실패가 관련이 없는 것 같으면 작업이나 파이프라인을 다시 실행하는 것을 고려합니다.

재검토 고려 사항#

때로는 머지 리퀘스트 검토가 간단하지 않으며 담당자와 검토자 사이에 주고받음이 필요합니다. 작업을 재검토하는 경우 이 머지 리퀘스트의 Commits 페이지로 이동하여 마지막 검토 이후 추가된 커밋의 내용을 읽습니다.

이 커밋들이 초기 검토의 우려 사항을 해결했는가?

큰 그림 생각#

이제 사려 깊고 도움이 되는 검토를 위한 준비 작업을 마쳤습니다. 처음에 머지 리퀘스트를 훑어볼 때 줄 수준 변경 사항에 대한 완전한 지식이 없었습니다. 이제 있습니다! 작성을 시작하기 전에 머지 리퀘스트의 줄별 보기에서 물러서서 다시 넓게 생각합니다. 이제 머지 리퀘스트가 무엇을 하려는지, 어떻게 하는지 알고 있습니다.

• 머지 리퀘스트의 변경 사항이 의도한 범위와 일치하는가? 그렇지 않다면 작업을 단순화하거나 여러 머지 리퀘스트로 분리해야 하는지 스스로에게 묻습니다. 자신의 지식 범위와 한계에 대해 정직하게 생각합니다.
• 코드 냄새가 감지되는가? 버그는 아니지만 미래의 품질, 유지 관리 가능성 또는 보안 문제를 가리키는 것이 있다면 주의를 기울입니다. 변경 사항에 대해 뭔가 이상하거나, 불분명하거나, 잘못 수행된 것 같은 느낌이 든다면 본능을 신뢰합니다. 코드는 기술적으로 올바를 수 있지만 미래에 문제를 일으킬 수 있는 약점을 포함할 수 있습니다.

최고의 도움이 되는 코드 검토는 줄별 수정에만 집중하지 않습니다. 유지 관리 가능성 및 기술 부채와 같은 장기적인 우려 사항도 고려합니다.

검토 완료#

이제 피드백을 제공할 시간입니다!

머지 리퀘스트 검토가 처음이라면 첫 댓글을 작성하기 전에 얼마나 많은 시간을 생각하는지 놀랄 수 있습니다. 코드베이스에 더 익숙해질수록 새 머지 리퀘스트를 더 빨리 이해할 것입니다. 그러나 더 복잡한 검토를 맡기 시작할 가능성도 있습니다.

검토 댓글 작성#

Start a review 기능을 사용하면 보류 중인 댓글에 생각을 기록할 수 있습니다. 이 댓글은 검토를 제출하기 전까지 다른 사람에게 표시되지 않습니다. 이렇게 하면 수신자에게 메시지 과부하를 방지하고 게시하기 전에 말을 다시 확인(및 변경)할 기회가 제공됩니다.

건설적이고 친절하게 작성하는 것을 기억합니다. conventional comments의 구조는 사려 깊고 건설적인 댓글을 작성하는 데 도움이 됩니다.

먼저 특정 줄이나 파일에 첨부하려는 댓글을 작성합니다:

1. Changes 탭을 선택합니다.

2. 질문하거나 피드백을 제공하려는 줄을 찾으면 여백에서 Add a comment to this line([comment])을 선택합니다. 이렇게 하면 diff 줄이 확장되고 댓글 상자가 표시됩니다.

3. 여러 줄을 선택하거나 전체 파일을 선택하여 댓글을 달 수도 있습니다:

   

4. 텍스트 영역에 첫 번째 댓글을 작성합니다. 검토 마지막까지 댓글을 비공개로 유지하려면 댓글 아래의 Start a review를 선택합니다.

5. 수정이 쉽게 초안을 작성할 수 있거나 작성자에게 더 나은 접근 방식을 보여주고 싶을 때 제안을 제공합니다. 코드 변경이 제안 형식에 비해 너무 크거나 복잡하면 변경을 요청하는 댓글을 남깁니다.

6. 파일과 코드의 개별 줄에 계속 댓글을 답니다. 각 댓글 후 Add to review를 선택합니다.

작업하면서 검토 댓글에 /label 또는 /assign_reviewer와 같은 퀵 액션을 사용할 수 있습니다. 보류 중인 댓글은 요청된 액션을 표시하지만 검토를 제출할 때까지 액션이 수행되지 않습니다. (나중에 /submit_review 퀵 액션으로 검토를 제출할 수도 있습니다!)

검토 요약#

파일별 및 줄별 피드백을 추가했으며 이제 검토를 요약할 준비가 되었습니다. 마지막으로 한 번 더 넓게 생각할 시간입니다.

1. 머지 리퀘스트의 Overview 페이지로 돌아갑니다.

2. 보류 중인 댓글을 스캔합니다. 도움이 되고, 사려 깊고, 친절하며 - 가장 중요하게 - 실행 가능해야 합니다. 발견한 문제를 수정하기 위한 명확한 다음 단계를 작성자에게 제공했는가?

3. 어조를 고려합니다. 가르치고, 토론하거나, 논의하고 있는가? 댓글이 목표를 달성하는가? 작성자라면 다음에 무엇을 해야 하는지 알겠는가? 좋은 행동을 강화하고 나쁜 행동에서 멀어지도록 작성자를 유도합니다.

4. 댓글이 여전히 의미가 있는가? 대형 머지 리퀘스트에서는 일부 댓글이 더 이상 유용하지 않거나, 그동안 일부 질문이 답변을 받았을 수 있습니다.

5. 일반적인 피드백을 위한 스레드를 시작합니다. 관련 없는 항목들이 같은 댓글에 묶이지 않도록 하여 스레드가 해결될 때 해결되지 않은 피드백이 숨겨지지 않도록 합니다. 가능한 주제:

   • 큰 함수를 더 작은 단일 목적 함수로 분리.
   • 의미 있는 변수 이름 사용.
   • 복잡한 코드를 설명하기 위한 더 많은 댓글 추가.
   • 엣지 케이스 및 오류 확인.

6. 요약 댓글을 위한 새 스레드를 시작합니다. 작성자가 할 일 항목에서 작업하는 경우 해당 사용자의 사용자 이름을 언급합니다. 명확하게 명시합니다:

   • 전반적인 결과는 무엇인가?
   • 검토를 마쳤는가, 아니면 더 많은 작업 후 이 머지 리퀘스트를 다시 보고 싶은가?

7. 오른쪽 상단에서 Your review를 선택하여 검토에 대한 세부 정보를 표시합니다:

   

8. 보류 중인 댓글을 검토합니다. 필요에 따라 편집합니다.

9. 검토 결과를 선택합니다.

   • Approve: 피드백을 남기고 변경 사항을 승인합니다.
   • Comment: 명시적인 승인이나 변경 요청 없이 일반적인 피드백을 남깁니다.
   • Request changes: 작성자가 피드백을 처리할 때까지 머지 리퀘스트 머지를 차단합니다.

10. 선택 사항. 검토 요약을 작성합니다. GitLab Premium 및 Ultimate 사용자는 Add summary([tanuki-ai])를 선택하여 요약을 만들 수 있습니다. 수행하려는 퀵 액션을 포함합니다.

또한 검토가 아닌 댓글의 텍스트에 /submit_review 퀵 액션을 사용할 수 있습니다.

머지 리퀘스트를 승인하고 검토자 목록에 표시되면 이름 옆에 녹색 체크 표시 [check-circle-filled]가 표시됩니다.

정리 작업 수행#

피드백을 제공한 후 정리합니다.

• 모든 보류 중인 댓글이 제출되었는지 확인합니다.
• 레이블 및 마일스톤을 업데이트합니다.
• 승인 요구 사항을 확인합니다.
  • 머지 리퀘스트의 각 작업 유형(백엔드, 프론트엔드, 문서)이 적절한 사람이 검토했는가?
  • 더 많은 검토가 필요하다면 다음 검토자의 사용자 이름을 언급하고 검토자로 추가합니다.
• 머지 위젯을 확인합니다.
  • 처리할 수 있는 차단 요소를 해결하고 처리할 수 없는 것에 대해 사용자를 지정합니다.
  • 검토를 위한 필요한 코드 소유자를 추가합니다.
• 이 머지 리퀘스트가 머지 준비가 되었는가? 머지 리퀘스트가 완전히 검토되고 승인되었다면 머지를 위해 메인테이너에게 할당합니다!

관련 주제#

• Conventional comments는 댓글에 도움이 되는 구조를 제공합니다.
• 효율적인 코드 검토 팁