Pull Requests의 마법

1. 병합에서 제안으로: Pull Request가 필요한 이유

지난 강의에서 우리는 로컬 컴퓨터에서 브랜치를 병합(merge)하는 법을 배웠습니다. 혼자 작업할 때는 잘 작동합니다. 하지만 프로젝트에 팀원이 함께 작업하고 있다면 어떨까요? 각자 변경사항을 기본 브랜치인 main에 바로 병합하면 곧 혼란이 생깁니다: 누군가 실수로 버그가 있는 코드를 추가하거나 빌드를 망가뜨리거나 동료의 중요한 작업을 삭제할 수 있습니다.

이를 방지하기 위해 팀 개발에서는 다른 접근 방식을 사용합니다. 변경사항을 바로 병합하는 대신, 먼저 병합 제안을 만듭니다. 이 제안은 Pull Request(약어 PR)라고 하며, 일부 플랫폼에서는 Merge Request라고 부릅니다.

Pull Request는 공식적인 요청입니다: “제 변경사항을 제 브랜치에서 가져와(pull) 기본 브랜치에 병합(merge)해 주세요.” 그러나 이것은 단순한 요청이 아니라, 코드가 main에 들어가기 전에 토론하고 검토하며 개선할 수 있는 플랫폼입니다.

2. Pull Request의 표준 워크플로

새 기능을 만들 때의 일반적인 워크플로를 단계별로 살펴보겠습니다.

새 작업을 위한 브랜치를 만들기 전에, 모든 완료된 커밋을 push하고 기본 브랜치 main을 Update Project로 업데이트했는지 확인하세요.

그렇지 않으면 로컬에 남아 있는 "잊힌" 커밋들이 새 Pull Request에 실수로 포함되어 동료들에게 혼란을 줄 수 있습니다.

1단계. 새 작업을 위한 브랜치 생성.

앞서와 마찬가지로 새로운 작업은 별도의 브랜치 생성으로 시작합니다. 예를 들어, 기여자 가이드 파일을 프로젝트에 추가하고 싶다면 feature/add-contribution-guide 브랜치를 만듭니다.

2단계. 변경사항을 만들고 브랜치를 GitHub에 푸시합니다.

새 브랜치에서 CONTRIBUTING.md 파일을 만들고(생성 후 Add 클릭) 다른 개발자에게 남길 메시지를 작성하세요. 그런 다음 이해하기 쉬운 메시지로 Commit and Push를 실행합니다. 예: docs: Add contribution guide.

이 단계가 핵심입니다! Pull Request는 이미 원격 서버에 존재하는 브랜치를 기반으로 생성됩니다. 따라서 PR을 만들기 전에 반드시 새 브랜치를 GitHub에 푸시해야 합니다.

3. IntelliJ IDEA에서 Pull Request 생성하기

브랜치가 GitHub에 올라갔으니 이제 Pull Request를 생성할 수 있습니다.

1단계. Pull Requests 탭을 엽니다.

IDE의 왼쪽 사이드 패널에서 Pull Requests 도구 창을 찾으세요. 열고 + 아이콘(또는 Create Pull Request 버튼)을 클릭하여 새 PR을 만듭니다.

2단계. PR 정보를 입력하세요.

IDE가 편리한 인터페이스를 자동으로 열어 줍니다. 여러분의 임무는 이를 잘 채우는 것입니다. 주요 필드를 살펴보겠습니다:

1. 제목: IDE가 종종 브랜치 이름이나 마지막 커밋 메시지를 여기에 넣습니다. 제목이 간결하고 명확하며 변경 사항의 핵심을 반영하는지 확인하세요.
2. 설명: 여기서 동료들에게 당신이 무엇을 했고 왜 했는지 자세히 설명합니다.
3. 리뷰어(Reviewers): 코드 검토를 맡을 한 명 또는 여러 명의 동료를 선택합니다. 학습용 프로젝트에서는 이 단계를 건너뛸 수 있지만 실제 작업에서는 필수입니다.
4. 담당자(Assignees): 보통 자신을 지정합니다. 이는 해당 작업의 작성자이자 리뷰 후 수정 책임자임을 의미합니다.

모든 필드를 채웠다면 Create Pull Request를 눌러 진행하세요.

4. 코드 리뷰: 검토와 토론

PR을 생성하면 가장 중요한 단계인 코드 리뷰가 시작됩니다. 동료들이 PR을 열어 변경 사항을 확인하고 댓글을 남길 수 있습니다.

IDE의 Pull Requests 탭에서 모든 토론을 바로 확인할 수 있습니다. 누군가 코드의 특정 줄에 댓글을 남기면 알림을 받고 브라우저로 전환하지 않고도 답글을 달 수 있습니다.

수정 요청을 받으면 어떻게 하나요?

매우 간단합니다! 새 PR을 만들 필요가 없습니다. 현재 브랜치에서 필요한 수정을 하고 새 커밋을 만든 뒤 푸시하면 됩니다. GitHub의 Pull Request는 자동으로 업데이트되어 기존 토론에 새 커밋이 추가됩니다.

5. 작업 완료: 병합과 브랜치 삭제

모든 코멘트가 해결되고 팀이 변경 사항을 승인하면(승인 받으면) Pull Request를 병합할 수 있습니다. 보통 수석 개발자나 리포지토리에서 권한이 있는 사용자가 이 작업을 수행합니다.

1단계. Merge

병합은 주로 GitHub 웹사이트나 IDE의 Pull Requests 창에서 이루어집니다. GitHub에서는 PR 아래에 큰 녹색 버튼 Merge pull request가 표시됩니다. 클릭하면 코드가 기본 브랜치 main의 일부가 됩니다.

2단계. 브랜치 삭제.

병합 후에는 해당 feature 브랜치가 더 이상 필요 없으므로 리포지토리를 정리하기 위해 삭제하는 것이 좋습니다. GitHub는 이를 제안하며 Delete branch 버튼을 표시합니다.

IDE에서도 로컬 브랜치 복사본을 삭제하고 main 브랜치에서 Update Project를 실행하여 병합 결과를 로컬로 가져오는 것을 잊지 마세요.

6. 좋은 커밋의 세 가지 규칙

좋은 커밋은 올바른 메시지뿐 아니라 적절한 내용도 포함합니다. 변경 이력이 깔끔하고 유용하며 전문적으로 보이도록 다음 세 가지 간단한 규칙을 지키세요.

규칙 1: 표준에 맞는 명확한 메시지 작성

커밋은 팀과 미래의 자신에게 보내는 메시지입니다. "fix"나 "update" 같은 메시지로 가득한 히스토리는 전혀 도움이 되지 않습니다. 가장 널리 쓰이는 표준 중 하나는 Conventional Commits입니다. 제안하는 구조는 다음과 같습니다:

<type>: <short description>

type은 변경사항의 분류를 나타내는 짧은 단어입니다:

• feat: (feature) — 새로운 기능에 사용.
• fix: — 버그 수정에 사용.
• docs: — 문서 변경에 사용.
• style: — 로직에 영향을 주지 않는 코드 포맷 수정.
• refactor: — 기능 추가나 버그 수정이 아닌 코드 개선.
• test: — 테스트 추가 또는 수정.
• chore: — 의존성 업데이트, 빌드 설정 등 루틴 작업.

예시:

• 나쁨: fixed bug
• 좋음: fix: Correct user login validation

• 나쁨: readme
• 좋음: docs: Update installation instructions

규칙 2: 한 커밋에 한 논리적 변경(원자성)

버그 수정, 새로운 기능 추가, 기존 코드 리팩터링을 하나의 커밋에 모두 담으려 하지 마세요. 그런 커밋은 리뷰하기 어렵고, 문제가 생겼을 때 되돌리기도 거의 불가능합니다.

각 커밋은 단 하나의 구체적인 작업을 해결해야 합니다.

• 나쁨: "Update user page"라는 메시지의 하나의 커밋이 아바타 필드 추가, 사용자 이름 유효성 검사 버그 수정, 버튼 색상 변경을 모두 포함하는 경우.
• 좋음: 세 개의 별도 커밋:
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. style: Update button colors on user page

작업 중 한 파일에서 너무 많은 변경을 했다는 것을 깨달았다면, IntelliJ IDEA는 파일 전체를 커밋하지 않고도 Commit 창에서 파일을 펼쳐 관련된 코드 조각(chunks)에만 체크 표시하여 커밋할 수 있게 해 줍니다.

규칙 3: 커밋은 프로젝트를 망가뜨려서는 안 된다

기본 브랜치의 각 커밋은 프로젝트를 빌드 가능한 상태로 유지해야 합니다. 커밋을 만들기 전에 최소한 코드가 컴파일되는지 확인하세요. 하지만 시스템의 다른 부분을 실수로 망가뜨리지 않았는지 어떻게 보장할 수 있을까요? 수동 검사만으로는 위험합니다.

여기서 자동화가 도움을 줍니다. 이 강의에서는 자동화 프로세스를 설정하지 않지만, 실제 프로젝트에서는 어떻게 동작하는지 알아두어야 합니다. 현대 팀은 GitHub Actions와 같은 지속적 통합(Continuous Integration, CI) 시스템을 사용합니다.

작동 원리

코드와 테스트를 작성합니다. 그런 다음 여러분이나 DevOps는 GitHub에 워크플로(workflow)를 설정합니다. 이제 Pull Request에 푸시하면 다음과 같은 일이 자동으로 발생합니다:

1. GitHub Actions가 이벤트를 감지하고 원격 서버에서 워크플로를 실행합니다.
2. 워크플로는 프로젝트를 자동으로 "빌드"하고 작성한 모든 테스트를 실행합니다.
3. 모든 테스트가 통과하면 GitHub의 커밋 옆에 녹색 체크표시가 나타납니다. 이는 팀 전체에 변경사항이 안전하다는 신호입니다.
4. 테스트 중 하나라도 실패하면 빨간 X가 표시됩니다. 이런 PR을 기본 브랜치에 병합하는 것은 오류가 수정될 때까지 절대 허용되지 않습니다.

            graph LR
            subgraph GitHub
            A[개발자] -- "push" --> B(리포지토리)
            B -- "이벤트: push" --> C{GitHub Actions}
            end

            subgraph Workflow
            C -- "실행" --> D[테스트_실행]
            D --> E[성공]
            D --> F[실패]
            end

            subgraph Notifications
            F --> G((Email))
            G --> H[개발자]
            G --> I[팀]
            end

            style F fill:#f99,stroke:#333,stroke-width:2px
            style G fill:#ccf,stroke:#333,stroke-width:2px
        

알림을 설정할 수 있습니다. 테스트가 실패하면 GitHub Actions가 여러분이나 팀 전체에 이메일을 보낼 수 있습니다. 이런 접근 방식은 테스트가 단순한 형식적 절차가 아니라 개발의 필수 요소이며, 각자가 자신의 코드 품질에 책임을 지는 문화를 만듭니다.