문서 전용 PR 일괄 적용

문서 전용 PR 일괄 적용은(는) 무엇을 하나요?

개요

소규모 문서 풀 리퀘스트 여러 개를 하나로 묶어 검토하면 더 효율적입니다. 이 절차는 검토가 완료된 여러 문서 전용 PR의 파일을 하나의 새로운 초안 PR로 복사하며, 각 소스 PR당 하나의 커밋을 만듭니다. 파일 내용은 수정 없이 정확히 복사되며, 소스 PR은 그대로 남습니다. 검토자가 일괄 PR을 병합하면 소스 PR은 이 절차의 어떤 작업 없이 자체 상태에 따라 종료됩니다.

사용 시기

• 여러 개의 열려 있는 문서 PR이 검토를 통과했고, 각 PR이 문서 경로만 수정한 경우.
• 검토자가 이들을 함께 담은 하나의 PR을 요청한 경우.

코드, 설정, 또는 검토를 통과하지 않은 소스 PR에는 사용하지 마십시오.

특징

• 작업 중인 체크아웃을 변경하지 않는 스크래치 워크트리 사용.
• 각 소스 PR의 상태, 베이스, 헤드, 파일 목록의 라이브 스냅샷을 가져와 가져온 헤드 커밋과 비교 확인.
• 닫힌 PR, 문서 폴더 외부 경로를 수정하는 PR, 메인 브랜치와 충돌하는 PR, 다른 열린 PR과 충돌하는 PR을 건너뛰는 규칙.
• 착지된 각 소스당 하나의 커밋을 만들며, 잘못된 소스에 대해 실행을 중단하는 assert 사용.
• 푸시 전 변경된 경로에 대한 게이트와 모든 파일의 blob을 소스 헤드와 비교하는 검증 블록.

장점

• 잘못된 소스가 있으면 실행이 중단되어 부분적으로 착지되는 것을 방지합니다.
• 착지된 모든 파일의 내용이 소스와 동일함을 증명합니다.
• 건너뛴 PR은 사유와 함께 목록에 표시되므로, 어떤 것도 조용히 누락되지 않습니다.
• 일괄 PR은 초안으로 열리므로, 최종 결정은 검토자가 내립니다.

절차

1. 스크래치 워크트리에서 작업합니다. 메인 브랜치와 소스 PR 헤드를 가져온 다음, 스크래치 폴더에 메인에서 새 브랜치를 생성합니다:

   git fetch origin main '+refs/pull/*/head:refs/remotes/origin/pr/*'
   git worktree add -b <batch-branch> <scratch-dir>/wt origin/main
   

   HTTPS 가져오기 또는 푸시가 인증에 실패하면, 자격 증명 헬퍼를 코드 호스트의 CLI로 설정하여 해당 명령어를 실행합니다(예: -c credential.helper= -c 'credential.helper=!gh auth git-credential'). 저장된 구성을 변경하지 말고, 토큰을 출력하지 마십시오.

2. 라이브 상태를 한 번 스냅샷합니다. 각 소스 PR에 대해 상태, 초안 플래그, 베이스 브랜치, 헤드 커밋, 파일 목록을 읽습니다. 또한 충돌 확인을 위해 열린 PR 목록을 가져옵니다. 각 소스의 헤드 커밋이 가져온 refs/remotes/origin/pr/<n> 커밋과 일치하는지 확인합니다.

3. 번호 순서대로 건너뛰기 또는 착지를 결정합니다. 다음 조건 중 하나라도 해당하면 PR을 건너뛰고 이유를 기록합니다:

   • PR이 열려 있지 않음.
   • 경로 중 하나라도 문서 폴더 외부에 있음.
   • 경로 중 하나라도 메인 브랜치에 이미 존재함. 메인에 이미 있는 경로의 경우 blob을 비교합니다. 내용이 동일하면 이미 이전에 착지된 것입니다. 내용이 다르면 리베이스가 필요합니다.
   • 다른 열린 PR이 해당 경로 중 하나를 수정함.

4. 각 PR을 하나의 커밋으로 착지합니다. 각 착지된 PR에 대해 헤드 커밋에서 파일을 체크아웃하고, PR을 명명하는 메시지로 커밋합니다. PR이 열려 있고, 헤드가 일치하며, 경로가 문서 폴더 아래에 있고, 그중 어느 것도 메인에 없는지 확인하는 루프에서 실행합니다. 실패한 assert는 실행을 중단합니다.

   git checkout <head-commit> -- <paths>
   git commit -m "docs: land #<n>"
   

5. 푸시 전에 변경 사항을 게이트합니다. 문서 폴더 외부의 변경된 파일 수는 0이어야 합니다. 변경된 총 파일 수는 각 PR의 경로 수 합계와 같아야 합니다.

6. 검증 블록을 만듭니다. 각 PR 및 각 경로에 대해 배치 브랜치의 HEAD에 있는 blob을 소스 헤드의 blob과 비교합니다. 각 PR에 대해 헤드, 경로 수, blob 수, MATCH를 보여주는 한 줄을 출력하고 합계를 더합니다. 블록을 그대로 배치 PR 설명에 붙여넣습니다.

7. 배치 PR을 초안으로 엽니다. 브랜치를 푸시한 다음, 메인을 기준으로 초안을 생성합니다. 제목에는 고려된 PR 수가 아니라 실제로 착지된 PR 수를 명시합니다:

   gh pr create --draft --base main --title "docs: land <k> reviewed docs PRs" --body-file <body-file>
   

8. 설명을 작성합니다. 문서 전용 diff에 대해 빌드가 건너뛰었다는 메모, 착지된 PR 목록(파일 수와 헤드 포함), 건너뛴 PR 목록(사유 포함), 검토자를 위한 플래그, 검증 블록을 포함합니다. 새 PR의 상태를 다시 읽고 메인을 기준으로 한 초안인지 확인합니다.

함정

• 초안 규칙 무시. 실행 지침에서 검토 준비 완료 PR을 요청할 수 있습니다. 실행 규칙에서 달리 명시하지 않는 한 초안으로 열고, 설명에 그렇게 명시하십시오.
• 다른 브랜치를 기반으로 한 소스 PR. 파일이 모든 경로 규칙을 통과하지만, 메인에 착지하면 PR의 의미가 달라집니다. 규칙에서 허용하는 경우에만 포함시키고, 정확한 드롭 커밋을 플래그로 표시하십시오.
• 병합 베이스 없음. 이러한 PR의 경우 병합 베이스 조회가 실패할 수 있으며, 베이스에 대한 diff가 오류를 발생시킵니다. 경로 소스로 라이브 파일 목록을 사용하십시오. 병합 베이스가 있는 경우에만 병합 베이스에 대한 diff와 교차 확인하십시오.
• 부분 착지. 메인에 이미 있는 파일을 수정하는 PR은 다른 파일이 새로운 파일이더라도 건너뛸 수 있습니다. 일부만 착지하지 마십시오.
• 누락된 경로 오류로 출력이 넘쳐나는 문제. 경로가 메인에 있는지 확인하는 검사는 각 누락된 경로에 대해 오류를 출력합니다. 해당 검사에서는 표준 오류를 /dev/null로 보내십시오.
• 최종 보고서 패딩. 건너뛴 목록과 사유, 플래그, 검증 합계를 보고하십시오. 모든 파일을 나열하지 마십시오.
• 그래프 또는 인덱스 누락. 저장소에 코드 인텔리전스 인덱스를 사용할 수 없는 경우, 보고서에 그 사실을 명시하고 경로 규칙을 건너뛰지 마십시오.

검증

• 배치 PR은 메인을 기준으로 한 초안입니다.
• 착지된 모든 파일의 blob이 소스 헤드와 일치하며, 검증 블록에 표시됩니다.
• 문서 폴더 외부에 변경된 파일이 없습니다.
• 건너뛴 모든 PR에는 설명에 사유가 있습니다.
• 소스 PR은 변경되지 않았습니다. 이 절차는 소스 PR을 병합, 승인, 닫거나 댓글을 달지 않았습니다.