큰 풀 리퀘스트는 검토하기 어렵고 병목 현상을 초래하며, 특히 짧은 시간에 많은 양의 코드를 생성하는 경우 더욱 그렇습니다. 끌어오기 요청 크기가 증가함에 따라 검토 품질도 저하됩니다. 검토자는 결과를 훑어보거나, 문제를 누락하거나, 미루고, 오래 방치되어 낡은 상태가 되고 병합 충돌이 발생할 때까지 끌어오기 요청을 그대로 둘 수 있습니다.
스택형 풀 리퀘스트는 큰 코드 변경 내용을 검토할 수 있게 합니다.
스택은 동일한 리포지토리에 있는 일련의 끌어오기 요청으로, 각 끌어오기 요청이 아래 끌어오기 요청의 분기를 대상으로 하여 단일 분기(일반적으로 주 분기)에 배치되는 순서가 지정된 체인을 형성합니다. 하나의 큰 끌어오기 요청 대신 더 작은 끌어오기 요청 집합을 가져옵니다. 각 끌어오기 요청에는 고유한 포커스가 있는 diff가 있으므로 팀원은 각 계층을 독립적으로 검토하고 승인할 수 있습니다.
이 자습서에서는 스택형 pull request를 사용하여 개별적으로 검토 가능한 계층에서 기능을 빌드하는 방법을 안내합니다. 이 예제에서는 앱에 사용자 인증을 추가하는 방법을 살펴보겠습니다.
GitHub CLI에서 gh stack 확장을 사용합니다.
필수 조건
이 자습서를 수행하려면 GitHub CLI 및 gh stack 확장 프로그램을 설치해야 합니다. 다음 항목이 필요합니다.
- GitHub CLI (
gh) 2.90.0 이상 및 Git 2.20 이상gh auth login를 사용하여 GitHub CLI을(를) 인증합니다.
- GitHub 푸시할 수 있는 리포지토리입니다.
GitHub CLI에서 gh stack 확장을 설치합니다.
gh extension install github/gh-stack
1. 코드를 생성하기 전에 스택을 설계하세요
좋은 스택은 집을 짓는 것과 같습니다: 강한 기초로 시작하고 벽체 골조를 세우고 배선을 설치한 다음 석고보드 마감을 합니다. 각 계층은 아래 계층에 의존하여 빌드됩니다. 결국 검토자는 아래에서 위로 풀 리퀘스트를 읽고 기능의 개발을 따를 수 있어야 합니다.
- 기능을 레이어로 분할합니다. 각 계층은 자체적으로 검토할 수 있는 일관된 단일 변경이어야 합니다.
- 풀 리퀘스트를 빠르게 읽을 수 있을 만큼 각 계층을 작게 유지합니다. 레이어가 검토를 위해 긴 설명이 필요하다고 느껴진다면 너무 클 수 있습니다.
- 경계를 직접 결정하세요. 스택의 형태를 직접 결정합니다.
- 종속성별로 레이어를 정렬합니다. 기본 변경 내용은 맨 아래에 있습니다. 그들에 의존하는 모든 것은 증가합니다. 인증의 경우 다음과 같습니다.
- 계층 1: 데이터 모델 및 마이그레이션
- 계층 2: CRUD 엔드포인트
- 계층 3: JWT 미들웨어 및 가드
- 계층 4: 통합 및 단위 테스트
2. 맨 아래 계층을 먼저 빌드합니다.
기초부터 스택을 시작합니다. 위의 모든 항목은 이 계층을 올바르게 구현하는 데 따라 달라집니다.
- 스택을 만들고 계획에 따라 첫 번째 계층을 빌드합니다.
gh stack init BRANCH-NAME-1로 만드세요. 접두사를 사용하여 분기 이름을 깔끔하게 유지하는 것이 좋습니다. - 계속 진행하기 전에 변경 사항을 직접 검토하세요. 아래쪽 계층의 실수가 위의 모든 분기에 전파되므로 계속 진행하기 전에 검토하세요.
3. 각 새 코드 계층을 위에 쌓습니다.
기반이 마련되면 기능의 나머지 부분을 한 번에 한 계층씩 빌드합니다.
- 다음 계층을 추가하고 아래 계층의 컨텍스트에서 구현하세요.
gh stack add BRANCH-NAME-NEXT로 스택 맨 위에 분기를 추가하고 그곳에서 작업을 커밋합니다. - 레이어가 너무 커지게 되면 원래 계획에서 벗어났는지, 아니면 실제로는 하나 대신 두 개의 레이어가 필요한지 고려합니다.
- 진행하면서 각 계층에 대해 새 분기를 만들면 모든 분기가 깨끗하고 독립적인 변경 사항(diff)으로 유지됩니다.
- 끌어오기 요청을 만들 준비가 되면
gh stack submit로 스택을 제출하세요. - 각 끌어오기 요청이 독립적으로 존재하도록 허용합니다. 명확한 제목과 레이어에 대한 간결하고 의미 있는 설명만으로도 충분합니다.
4. 검토를 요청하기 전에 풀 리퀘스트를 직접 검토합니다.
각 레이어는 작기 때문에 자체 검토도 더 쉬워집니다. 팀원을 참여시키기 전에 모든 브랜치를 한 번 검토하세요. 검토자가 이미 신뢰하는 변경 내용을 받아야 합니다.
- 검토를 요청하기 전에 각 브랜치에서 테스트, linter 및 코드 검사를 실행하여 각 계층이 표준을 충족하는지 확인합니다.
5. 맨 아래에서 시작하여 스택에 대한 검토를 요청하세요
레이어가 빌드되면 검토자는 큰 코드 벽 대신 작은 변경 사항 비교를 얻습니다.
- 종속성 간 결합도가 높다면 스택의 맨 아래에서부터 검토를 요청하여 후속 검토 전에 변경 사항을 스택의 상위 계층으로 반영할 수 있습니다.
- 서로 다른 계층에 대해 별도의 검토자들로부터 검토가 필요한 경우 검토자는 병렬로 작업할 수 있습니다. 한 사람은 데이터 모델을 검토할 수 있고 다른 사용자는 엔드포인트를 검토할 수 있으며, 누구도 전체 기능을 검토하느라 애쓸 필요가 없습니다.
6. 피드백을 바탕으로 반복 개선
검토 피드백은 전체 기능이 아닌 레이어에 개별적으로 적용됩니다. 스택을 사용하면 올바른 레이어를 제자리에 고정하고 변경 사항을 위쪽으로 전달할 수 있습니다.
- 검토자가 플래그를 지정한 계층을 수정하세요. 올바른 브랜치로 이동하여 변경한 후 거기에서 커밋합니다.
- 각 수정 사항은 해당 레이어에 그대로 두세요. 잘못된 분기에서 변경한 내용은 혼동을 일으키고 상위 단계에서 오류를 만들 수 있습니다.
gh stack down,gh stack up, 또는gh stack checkout BRANCH-NAME를 사용하여 분기를 탐색합니다. 그런 다음 변경 내용을 커밋하고, 위의 분기를 리베이스하려면gh stack rebase --upstack를 실행하고, 그런 다음gh stack push를 실행하여 변경 사항을 스택 위로 반영합니다.
7. 아래 레이어에서 병합
스택은 기본 분기를 가리키는 계층에서 시작하여 순서대로 병합됩니다. 레이어를 한꺼번에 병합하거나 하나씩 병합하면 GitHub이 자동으로 다음 레이어의 대상을 main으로 변경합니다.
- 스택을 맨 아래에서 위로 한 번에 하나씩 병합하거나, 스택의 어느 지점에서든 병합하면 병합한 풀 리퀘스트 아래에 있는 모든 브랜치가 맨 아래에서 위로 병합됩니다.
- 각 레이어의 diff는 부모에 대해 정확히 동일하게 유지되며 베이스만 바뀌므로 진행 중인 작업이나 검토에 영향을 주지 않고 한 번에 레이어를 쉽게 병합할 수 있습니다.
- 각 계층이 승인되고 검사가 통과되면 순서대로 병합되도록 병합 큐를 사용합니다. 전체 스택이 한꺼번에 완료될 때까지 기다릴 필요는 없습니다.
최상위 계층이 병합되면 전체 기능이 반영됩니다. 모든 조각은 하나의 큰 풀 리퀘스트보다는 작고 의도적인 변화로 더 효과적으로 검토되었습니다.