머지 리퀘스트 검토는 코드베이스에 고품질 코드만 반영되도록 보장하는 데 도움이 됩니다. 이 튜토리얼은 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. 이 작업을 검토하기에 적합한 사람입니까? 필요한 검토 유형이 본인의 역량 및 능력과 맞습니까?

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

• 작성자는 누구입니까? 이 사람의 작업 방식을 잘 알고 있습니까? 잘 아는 사람이라면 평소 코드베이스의 어느 부분을 주로 작업합니까? 작성자에 대한 이러한 지식은 이후 변경 사항을 얼마나 면밀히 살펴볼지 가늠하는 데 도움이 됩니다.
• 목표는 무엇입니까? 설명을 읽고 작성자의 의도를 이해합니다.
• 초안(draft)입니까? 초안은 대개 미완성이거나 이론적인 해결책인 경우가 많습니다. 초안 머지 리퀘스트는 완성된 머지 리퀘스트와는 다른 수준의 검토가 필요할 수 있습니다.
• 문제를 어떻게 재현할 수 있습니까? 설명에 문제를 재현하는 방법, 변경 사항을 테스트하는 방법, 새 기능을 사용해 보는 방법이 나와 있습니까? 참고할 스크린샷이 포함되어 있습니까?

설명 아래에서 머지 리퀘스트 위젯을 확인해 이 작업의 현재 상태를 파악합니다. 다음 예시는 승인이 누락되었고, 아직 초안 모드이며, 열려 있는 토론 스레드가 있는 머지 리퀘스트의 병합 위젯을 보여줍니다.

• 이슈와 상호 링크되어 있습니까? 설명과 병합 위젯에서 다른 이슈로의 링크를 확인합니다. 어떤 머지 리퀘스트는 단순하지만, 어떤 머지 리퀘스트는 왜 만들어졌는지 이해하려면 해당 이슈를 읽어야 합니다. 더 복잡한 머지 리퀘스트일수록 전체 정보가 담긴 이슈를 다시 가리켜야 합니다.
• 파이프라인 상태는 어떻습니까? 파이프라인이 초록색입니까? 빨간색 파이프라인은 문제를 나타냅니다. 미완료되었거나 취소된 파이프라인이 보인다면 아직 이 작업의 병합 가능 여부를 완전히 평가할 수 없습니다.

관련 이슈 확인하기#

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

• 문제와 해결책이 분리되어 있습니까? 이슈는 문제를 설명하고 조사해야 하며, 머지 리퀘스트는 해결책에 집중해야 합니다.
• 머지 리퀘스트 작성자가 이슈에 관여하고 있습니까? 검토 과정 전반에서 누가 문제(또는 기능)를 정의하는 데 도움을 주었는지 생각해 봅니다. 이상적으로는 그 사람들도 머지 리퀘스트에 관여해야 합니다.

사이드바 확인하기#

• 어떤 레이블이 붙어 있습니까? 레이블은 머지 리퀘스트의 내용을 짐작할 수 있는 단서를 제공합니다. 팀의 워크플로에 따라 불완전하거나 누락된 레이블은 문제가 되지 않을 수도 있고, 이 머지 리퀘스트에 전체 정보가 부족하다는 신호일 수도 있습니다.

  • 레이블이 본인의 전문 분야와 일치한다면 이 머지 리퀘스트를 검토하기에 적합한 후보일 가능성이 큽니다.
  • 레이블이 본인에게 없는 전문 분야와 일치한다면 머지 리퀘스트를 다른 리뷰어에게 재배정해야 할 수도 있습니다.
  • 워크플로에서 요구하는 레이블을 추가합니다.

  다음 예시에서는 정확한 레이블을 잘 모르더라도 이 머지 리퀘스트가 데이터베이스 버그에 관한 것임을 알 수 있습니다.

  

• 리뷰어는 누구입니까? 리뷰어 목록의 이름을 훑어봅니다. 설명과 (선택적으로) 레이블을 기준으로 예상한 작업 유형과 일치합니까? 누가 있는지와 누가 없는지 모두 고려합니다. 그 이름들은 이 머지 리퀘스트가 검토 주기의 어느 단계에 있는지에 대해 무엇을 알려줍니까? 누군가를 추가하거나 제거해야 합니까?

• 이미 승인한 리뷰어가 있습니까? 해당 리뷰어와 그들의 전문 분야를 알고 있다면 제안된 변경 사항 중 어떤 부분에 주의를 기울여야 하는지 어느 정도 감을 잡을 수 있습니다.

  다음 예시에서는 Thomas와 Nick 이 모두 리뷰어입니다. Thomas는 아직 머지 리퀘스트를 검토하지 않았고(❌), Nick은 검토를 마치고 승인했습니다(✅).

  

댓글 확인하기#

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

댓글에서 이전 검토의 흔적이 보입니까? 댓글 수가 많다면 이 작업을 얼마나 깊이 검토할지에 영향을 줄 수 있습니다.

코드 변경 사항 읽기#

이제 제안된 변경 사항을 읽을 준비가 되었습니다. 큰 머지 리퀘스트라면 본격적으로 살펴보기 전에 변경 사항을 먼저 훑어봅니다. 줄 단위로 변경 사항을 읽기 시작하기 전에 무엇을 예상해야 할지 이해를 쌓습니다.

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

Changes 페이지를 처음 열면 먼저 큰 틀의 세부 사항에 집중합니다.

• 어떤 파일이 변경되었습니까? 파일 브라우저([file-tree])를 펼쳐 변경된 파일 목록을 확인합니다. 이 파일들이 익숙합니까? 코드베이스의 어느 부분에 있는 파일입니까?

  

• 파일 목록이 예상과 일치합니까? 이미 머지 리퀘스트의 설명을 읽었습니다. 이 파일들이 이런 종류의 작업에서 변경될 것으로 예상한 파일입니까? 예상하지 못한 파일의 변경이나, 예상했지만 빠진 변경 사항에 특히 주의를 기울입니다.

• 줄이 추가, 삭제, 변경되었습니까? 이 숫자들은 더 깊이 읽을 때 어떤 종류의 작업을 예상해야 하는지 알려줍니다. 새 기능입니까, 제거된 기능입니까, 동작 변경입니까?

• 테스트가 변경되었습니까? 테스트 스위트에 속한 파일이 있습니까? 없다면 작성자에게 테스트를 업데이트하도록 요청해야 할 수도 있습니다.

• 기능 플래그가 사용됩니까? 기능 플래그가 보인다면 더 깊이 읽을 때 그 사용 방식을 확인해야 한다는 점을 메모해 둡니다.

변경 사항 훑어보기를 마쳤다면 이제 변경 사항을 줄 단위로 읽을 준비가 된 것입니다.

각 파일을 자세히 살펴보기#

이제 이 머지 리퀘스트에 포함된 변경 사항에 대해 대략적인 감을 잡았습니다. 이제 본격적으로 전체 변경 사항을 읽을 차례입니다. 자신의 지식이 강한 부분과 약한 부분을 인식합니다. 이 프로젝트를 잘 알고 있습니까? 변경 사항이 본인이 익숙한 언어로 작성되었습니까?

• 변경 사항이 명확하고 이해하기 쉽습니까?
• 기능 플래그가 사용됩니까? 변경 사항이 기능 플래그의 존재 여부를 테스트합니까? 플래그가 비활성화되었을 때 기능 플래그가 적용된 변경 사항이 실수로 노출되지 않도록 합니다.
• 성능이 좋습니까? 직접 성능을 테스트하는 데 문제가 없습니까, 아니면 성능에 대해 더 깊이 아는 리뷰어를 추가해야 합니까?
• 단순화할 수 있습니까?
• 에지 케이스를 고려하고 있습니까?
• 주석과 문서화가 올바르게 되어 있습니까? 좋은 코드는 작성자뿐 아니라 다른 사람도 유지 관리할 수 있어야 합니다. 작성자가 이 작업을 유지 관리 가능하게 만들 만큼 충분한 설명을 제공했습니까?
• 팀의 스타일 기준을 따르고 있습니까?
• 하위 호환성이 있습니까? 이 작업이 호환성을 깨는 변경입니까? 데이터 손실을 일으킬 수 있습니까?
• 보안 문제가 다뤄졌습니까? 변경 사항이 프로젝트에서 보안에 특히 민감한 영역에 있습니까? 민감한 데이터를 적절히 처리합니까? 사용자 입력을 받고, 그 입력이 살균(sanitize)되었습니까? 보안에 대해 더 깊이 아는 리뷰어를 추가해야 합니까?
• 디버깅용 코드가 그대로 남아 있지는 않습니까?

변경 사항의 종류에 따라 코드베이스에 미치는 영향이 다릅니다. 큰 틀에서 다음을 고려합니다.

• 추가된 줄: 새 코드는 기존 동작을 수정해서는 안 됩니다. 새로운 동작이 테스트되고 있습니까? 테스트가 충분히 세밀합니까?
• 삭제된 줄: 삭제가 깔끔하고 완전합니까? 삭제된 코드와 테스트의 범위가 서로 일치합니까? 양쪽 어디에도 부분적인 스텁이 남아 있지 않도록 합니다.
• 변경된 줄: 추가된 줄과 삭제된 줄이 대략 비슷하다면 이 변경이 기존 코드의 리팩터링입니까? 리팩터링이라면 이전 코드가 무엇을 했는지, 새 코드가 그것을 어떻게 다르게 수행하는지 이해하고 있습니까? 동작 변경이 설명에 명시된 작성자의 의도와 일치합니까? 테스트는 여전히 제대로 동작합니까?

코드 테스트하기#

안타깝게도 이 부분에서는 많은 가이드를 드릴 수 없습니다. 모든 프로젝트는 다르기 때문입니다. 애플리케이션을 직접 알지 못하는 상태에서는 변경 사항을 테스트하는 방법을 알려드릴 수 없지만, 고려할 만한 몇 가지 질문은 제시할 수 있습니다.

• 동작합니까? 겉보기엔 단순한 질문이지만 항상 염두에 둘 만큼 중요합니다. 코드는 지저분하고 복잡하며 문서화되어 있지 않아도 동작할 수 있습니다.

• 검토 과정이 어느 단계까지 진행되었습니까? 검토 과정의 초반입니까, 후반입니까? 본인은 전문가입니까?

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

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

파이프라인 확인하기#

머지 리퀘스트의 Pipelines 탭으로 이동해 파이프라인 상태를 확인합니다. 파이프라인이 성공했을 때만 머지 리퀘스트를 승인합니다. 다음 예시에서는 여러 job 이 실패했습니다.

• 예상된 테스트가 모두 실행되었습니까? 파이프라인이 단지 초록색인지가 아니라 완전한지 확인합니다.
• 실패한 테스트가 있습니까? Failed jobs를 펼쳐 어떤 테스트가 실패했는지(있다면) 확인합니다.
• 실패한 각 job에서 무슨 일이 있었습니까? 실패한 job을 각각 선택합니다. 출력을 스크롤 하면서 실패, 오류, 빨간색으로 표시된 줄에 대한 언급을 살펴봅니다. 검토 댓글을 작성할 때 무엇을 고쳐야 하는지, 어떻게 고쳐야 하는지 작성자가 이해하도록 돕고 싶을 것입니다.
• 실패가 변경 사항과 관련이 있습니까? 실패가 무관해 보인다면 job 이나 파이프라인을 다시 실행하는 것을 고려합니다.

재검토 시 고려 사항#

머지 리퀘스트 검토가 항상 단순하지는 않으며 담당자와 리뷰어 사이에 여러 차례 의견을 주고받아야 할 때도 있습니다. 작업을 재검토하는 경우 이 머지 리퀘스트의 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] 가 나타납니다.

정리 작업 수행하기#

피드백을 제공한 후에는 마무리 정리를 합니다.

• 보류 중인 댓글이 모두 제출되었는지 확인합니다.
• 레이블과 마일스톤을 업데이트합니다.
• 승인 요구 사항을 확인합니다.
  • 머지 리퀘스트에 포함된 각 유형의 작업(백엔드, 프론트엔드, 문서)이 적합한 사람에게 검토받았습니까?
  • 검토가 더 필요하다면 다음 리뷰어의 사용자 이름을 언급하고 리뷰어로 추가합니다.
• 병합 위젯을 확인합니다.
  • 처리할 수 있는 차단 요소는 처리하고, 처리할 수 없는 것은 도움을 줄 사용자를 배정합니다.
  • 검토가 필요한 Code Owner를 추가합니다.
• 이 머지 리퀘스트가 병합할 준비가 되었습니까? 머지 리퀘스트가 완전히 검토되고 승인되었다면 병합을 위해 Maintainer에게 배정합니다.

관련 주제#

• Conventional comments는 댓글에 유용한 구조를 제공합니다.
• 효율적인 코드 리뷰 팁