대규모 다국어 데이터 플랫폼 모노레포를 수정하고 풀 리퀘스트를 준비한다

## 첫 수정 전에 Git 원격 저장소를 확인하고 알맞은 브랜치를 고른다 세션에서 처음으로 편집하거나 테스트하기 전에 다음을 수행한다. 1. 개인 fork와 권위 있는 upstream remote를 식별한다. 각 역할이 불분명하면 표준 remote 구성을 설정해 달라고 요청한다. 2. upstream 기본 branch의 타임스탬프를 확인하고 로컬 참조가 오래되었으면 새로 고친다. 3. working tree를 검사하고 컨텍스트를 전환하기 전에 커밋하지 않은 변경 사항을 보호해 달라고 사용자에게 요청한다. 4. 작업에 따라 branch를 선택한다. 기존 리뷰에서는 해당 head branch를 확인하고, 일치하는 로컬 branch가 있으면 이를 사용한 뒤 전환 사실을 보고한다. 일치하는 branch가 없으면 이를 fetch할지, 이름이 다른 로컬 branch를 사용할지 묻는다. 새 편집에는 upstream 기본 branch에서 만든 격리된 worktree를 권장 옵션으로 제시하거나, 같은 branch를 기반으로 새 branch를 제시한다. 테스트만 수행하는 작업에는 upstream 기본 branch를 사용한다. ## 골든 테스트 출력과 프로토콜 파일은 직접 고치지 않고 다시 생성한다 golden 테스트 출력은 이를 생성하는 테스트 하네스에 속한다. 실행하거나 업데이트하기 전에 스위트 문서를 읽고, 생성된 기대 결과 파일을 절대로 직접 편집하지 말며, 지원되는 워크플로를 통해 다시 생성한다. 결과를 받아들이기 전에 생성된 diff를 주의 깊게 검토한다. 프로토콜 정의는 해당 스키마 원본에 속한다. 메시지나 필드를 변경하기 전에 정의와 함께 저장된 문서를 읽고, 생성된 프로토콜 산출물을 수동 편집 대상에서 제외한다. ## CI 전에 코드를 ASCII로 유지하고 한 줄 길이 제한을 지킨다 문자열 리터럴이나 테스트 픽스처의 내용에 다른 문자가 정말 필요한 경우가 아니면 식별자, 코드, 주석을 ASCII로 유지한다. 주석에 모르는 사이 들어가기 쉬운 조판용 대시, 스마트 따옴표, 줄임표, 줄 바꿈 없는 공백이 변경 파일에 있는지 표본 검사한다. 소스 행은 일반적으로 100자인 저장소 제한 안에 유지한다. 추가하거나 변경한 소스 파일을 빠르게 검사하면 import, package 선언, URL에 대한 예외를 대략 반영할 수 있지만 이는 참고 사항일 뿐이다. 언어별 linter가 최종 기준이다. ## 테스트에 충분한 가장 작은 JVM 테스트 기반을 고른다 필요한 동작을 제공하는 가장 작은 테스트 기반을 선택한다. 단순한 runtime 또는 유틸리티 테스트는 공통 timeout, 임시 파일, logging, 오류 helper만 제공하는 핵심 스위트를 사용해야 한다. 논리 plan, analyzer, optimizer 또는 planner 테스트는 SQL 세션을 시작하지 않는 plan 테스트 기반을 사용해야 한다. SQL 또는 테이블 테스트는 쿼리 테스트 기반을 사용하고 명시적인 세션 provider를 mixin으로 추가해야 한다. 일반 SQL 테스트에는 프로세스 내부 세션을 선택하고, warehouse 동작이 필요할 때만 warehouse 지원 provider를 선택한다. 주변 테스트가 사용한다는 이유만으로 범위가 더 넓은 픽스처의 비용을 부담하지 않는다. ## 로컬·원격·혼합 Python 테스트에 맞는 테스트 기반을 고른다 단순한 Python 테스트는 표준 단위 테스트 기반을 사용해야 한다. 컨텍스트 수준 테스트는 격리를 위해 테스트마다 새 실행 컨텍스트를 만들거나, 속도를 위해 클래스마다 하나를 재사용할 수 있다. SQL과 DataFrame 테스트는 공유 classic 세션 기반을 사용해야 하며, DataFrame 확장 테스트에는 columnar 실행과 전문 assertion을 추가할 수 있다. 원격 프로토콜 테스트에는 별도의 판단이 필요하다. 서버가 필요 없으면 plan만 처리하는 mock 픽스처를 사용하고, 실제 원격 동작에는 재사용하는 원격 세션을 사용하며, 동등성 검사에는 classic과 remote를 혼합한 픽스처를 사용한다. SQL 유틸리티, 구조화된 오류 assertion, 동등성 helper는 필요한 runtime을 생성하는 경우가 아니라면 테스트 기반이 아닌 mixin이나 독립 helper로 취급한다. ## 바뀐 모듈만 빌드·테스트하고, 전체 테스트 전에 묻는다 빌드와 테스트에는 큰 비용이 들 수 있다. 사용자가 테스트를 명시적으로 요청했다면 실행한다. 그렇지 않다면 시간이 오래 걸리는 전체 스위트 검증을 시작하기 전에 추가 편집이 예정되어 있는지 묻는다. 저장소의 더 빠른 증분 빌드 도구를 우선하고, 영향받은 모듈과 해당 테스트 코드만 컴파일하며, 반복 작업 중에는 단일 스위트 또는 이름을 지정한 케이스를 실행한다. 증분 빌드 shell을 열어 두는 것이 반복적인 모듈 테스트 시간을 단축한다면 계속 열어 둔다. 빌드된 backend에 의존하는 Python 스위트는 필요한 기능 프로필을 먼저 빌드하고, 사용자가 선택한 가상 환경이나 문서에 명시된 기본 환경을 활성화하며, 그 환경이 없을 때만 생성한다. 프로젝트 테스트 runner의 스위트 및 케이스 selector를 사용한다. ## 하나를 고치기 전에 실패한 CI 검사를 모두 나열한다 특정 실패를 조사하기 전에 리뷰 대상 commit에서 실패한 모든 검사를 열거한다. 테스트 요약 검사가 통과했거나 존재하지 않는다고 해서 CI 전체가 성공했다고 입증되는 것은 아니다. linter, 라이선스, 의존성, 호환성 검사, 컴파일, 문서 빌드는 테스트 annotation이 없는 별도 job에서 실패할 수 있다. 테스트 job에서는 실패 annotation을 사용하여 스위트, 케이스, 메시지를 가져온다. 테스트가 아닌 job에서는 실패한 단계를 식별하고 해당 job에 초점을 맞춘 log를 읽는다. 구조화된 annotation에 유용한 근거가 이미 있으면 매우 큰 분할 테스트 log를 다운로드하지 않는다. ## 닫힌 것으로 보이는 풀 리퀘스트가 실제로 병합되었는지 확인한다 닫힘으로 표시된 리뷰가 거부되었다고 단정하지 않는다. 일부 프로젝트는 사용자 정의 도구로 merge하므로, 호스팅 서비스가 성공적으로 merge된 리뷰를 기본 merge 타임스탬프 없이 닫힌 상태로 표시할 수 있다. 프로젝트의 merge 상태 helper를 사용하여 변경 사항이 반영되었는지, 어떤 기본 branch나 유지보수 branch에 포함되었는지 확인한다. 열림, merge됨, merge 없이 닫힘을 서로 다른 결과로 취급하고, 인증 부재, 얕은 이력, 알 수 없는 리뷰, upstream remote 부재는 환경 제약으로 보고한다. ## 풀 리퀘스트 제목과 설명을 프로젝트 형식대로 쓴다 초안, 작업 중, 사소한 변경 또는 자명한 변경에 대해 문서화된 예외를 포함하여 issue 식별자와 component tag에 관한 프로젝트 제목 규칙을 따른다. diff에서 제목을 추론한다. 필수 issue가 없으면 정확한 component와 issue 유형 또는 참조할 상위 항목을 지정하여 프로젝트 helper로 생성하고, 생성된 issue와 필드를 리뷰할 수 있도록 눈에 잘 띄게 표시한다. 설명을 작성하기 전에 저장소의 pull request template을 읽고 모든 섹션을 작성한다. issue tracker가 축약된 제목 tag 대신 전체 component 이름을 요구하면 전체 이름을 사용한다. ## 자신의 fork에만 push하고, 외부에 쓰기 전에 허락을 받는다 권위 있는 upstream 저장소에는 절대로 `push`하지 말고 기여자의 fork에만 `push`한다. 사용자가 명시적으로 요청하지 않는 한 이미 remote에 있는 commit을 `force-push`하거나 `amend`하지 않는다. remote branch가 앞서 나갔다면 `push`하기 전에 `fetch`하고 `rebase`한다. commit `push`, pull request 생성, issue 생성, 댓글 게시 등 외부 쓰기를 수행하기 전에 명시적인 승인을 받는다. 프로젝트에서 지원하는 인증된 client를 사용한다. 이를 사용할 수 없다면 필수 워크플로를 우회하지 말고 리뷰 URL이나 정확한 인계 지침을 준비한다. ## 변경이 처음 릴리스되는 브랜치의 버전 번호를 쓴다 코드에 버전 annotation, 설정 버전 또는 호환성 제외 항목이 필요하면 변경 사항이 가장 먼저 릴리스되는 branch의 버전을 사용하고 snapshot suffix를 제거한다. 유지보수 branch를 기반으로 한 리뷰에는 해당 branch의 버전을 사용한다. 기본 branch를 기반으로 한 리뷰에서 변경 사항을 일반적으로 최신 릴리스 branch로 backport한다면 최신 릴리스 branch의 버전을 사용한다. 호환성을 깨는 변경이나 binary 비호환 변경 또는 중요한 backport가 정당화되지 않는 의존성 업그레이드처럼 기본 branch에만 적용되는 작업에 한해서 기본 branch의 버전을 사용한다. 릴리스 경로가 불명확하면 기본 branch만 보고 추론하지 말고 질문한다. ## 보안 문제를 보고하기 전에 프로젝트의 보안 정책을 읽는다 보안 문제를 보고하기 전에 저장소의 보안 정책과 위협 모델을 읽는다. 선언된 적용 범위, 제외된 사례, 보안 발견으로 보지 않는다고 문서화된 사례를 확인하여, scanner 결과를 프로젝트가 실제로 보장하는 내용에 비추어 평가할 수 있게 한다. 보안 조사를 일반적인 버그 분류와 분리하고, 관련 근거를 보존하며, 발견 사항을 문서화하는 동안 자격 증명이나 민감한 로컬 데이터를 노출하지 않는다.