사람이 검토하고 제출할 수 있도록 코드 기여 준비하기

## 저장소 규칙을 따르고 관리자의 승인 기다리기 리포지토리의 기여 가이드, 인공지능 정책, 디렉터리별 에이전트 지침을 변경할 파일에 적용되는 기준으로 삼습니다. ### 적용할 규칙 확인 - 편집하기 전에 루트의 기여 및 보안 정책을 읽습니다. - 특수 목적 디렉터리에서 작업할 때는 런타임 동작, 공개 인터페이스, 통합, 문서 또는 테스트에 관한 해당 디렉터리의 지침도 적용합니다. - 지침이 충돌하면 구현하기 쉬운 규칙을 임의로 선택하지 말고 작업을 중단한 뒤 충돌 내용을 알립니다. - 선택적 에이전트 기능은 클라이언트가 지원하고 리포지토리 정책을 무효화하지 않는 경우에만 사용합니다. ### 승인 관문 - 브라우저 자동화, 호스팅 서비스의 명령줄 도구 또는 서비스 API를 통해 이슈, 풀 리퀘스트 또는 풀 리퀘스트 초안을 제출하지 않습니다. - 사람이 검토한 뒤 전송할 수 있도록 리포지토리의 템플릿을 사용해 바로 붙여 넣을 수 있는 제출문 초안을 작성합니다. - 관련 이슈의 분류가 완료되고 담당 기여자에게 배정되기 전에는 브랜치를 푸시하거나 공개 제출용 자료를 준비하지 않습니다. - 관리자의 지시가 기록되어 있지 않으면 사소하지 않은 기능, 공개 인터페이스 변경, 리팩터링 또는 동작 변경을 구현하지 않습니다. 지시가 없으면 제안 단계에서 중단합니다. ## 비밀 정보를 커밋에 넣지 않고 테스트를 실제 서비스에 연결하지 않기 작업 전반에 걸쳐 자격 증명, 증거의 품질, 리포지토리 기록, 테스트 격리를 보호합니다. ### 반드시 지켜야 할 규칙 - 비밀, 자격 증명, 비공개 제공업체 데이터 또는 민감한 환경 값을 절대 커밋하지 않습니다. - 테스트 결과, 승인, 인용, 검토 상태 또는 호환성 주장을 절대 조작하지 않습니다. - 단위 테스트는 실제 운영 중인 모델, 제공업체 또는 외부 애플리케이션 서비스에 연결해서는 안 됩니다. - 결정론적 대체 수단과 테스트 프로세스에서 운영 서비스의 자격 증명을 제거하는 환경을 사용합니다. - 출처가 명확하고 관리자의 동의를 받지 않은 생성 미디어, 대용량 생성 자산 또는 합성 데이터 세트를 추가하지 않습니다. - 라이선스 삽입을 리포지토리 자동화가 담당하는 경우에는 라이선스 헤더를 수동으로 추가하지 않습니다. - 요청받지 않은 주석은 추가하지 않습니다. 변경으로 인해 내용이 부정확해지는 경우가 아니라면 기존 주석, 문서화 문자열, 라이선스 헤더를 보존합니다. ### 보호 대상 파일 작업에서 리포지토리의 재생성 워크플로를 명시적으로 요구하지 않는 한 변경 기록, 생성된 파일, 잠금 파일, 검증 스냅샷 또는 기타 도구 관리 산출물을 수동으로 편집하지 않습니다. 변경 기록이 자동으로 생성되는 경우에는 릴리스 노트의 배경 정보를 제안서나 제출 초안에 포함합니다. ## 의존성은 꼭 필요할 때만 바꾸고 고정된 도구 사용하기 대체 실행 경로를 임의로 만들지 말고, 프로젝트에서 공식적으로 고정한 환경과 작업 명령을 사용합니다. ### 의존성 변경 - 작업에 필요한 경우가 아니면 의존성을 추가하거나 업데이트하지 않습니다. - 일시적인 조사에는 커밋된 의존성 상태를 변경하지 않는 격리된 환경을 사용합니다. - 의존성 변경이 필요한 경우에는 가장 범위가 좁고 적합한 의존성 그룹이나 선택적 기능 집합에 배치합니다. - 명확한 호환성 범위를 지정하고 선택적 통합을 기본 설치 경로로 옮기지 않습니다. - 의존성 및 잠금 파일 변경을 관련 없는 편집과 분리합니다. ### 도구 사용 - 설치, 테스트, 문서화, 서식 지정, 정적 분석에는 리포지토리에 고정된 런타임 및 도구 버전을 사용합니다. - 공식 검증 명령과 진단 명령을 구분합니다. 독립형 린터나 타입 검사기는 진단에 도움이 될 수 있지만, 리포지토리가 요구하는 커밋 전 검사나 공식 검증 경로를 대체하지는 못합니다. - 광범위한 스테이징, 커밋 또는 리포지토리 전체 검사를 수행하는 스크립트는 영향력이 큰 도구로 취급합니다. 명시적으로 필요한 경우에만 실행하고, 가능하면 변경 사항이 없는 작업 트리에서 실행합니다. ## 변경 종류에 맞춰 필요한 테스트 고르기 실제 변경 유형에 따라 필요한 최소한의 검증을 선택한 뒤, 공유 동작이나 호환성 위험으로 인해 필요한 경우에만 범위를 확대합니다. ### 검증 매트릭스 - 문서 또는 리포지토리 메타데이터: 변경된 파일을 검사합니다. 렌더링, 링크, 예제 또는 문서 설정이 영향을 받을 수 있으면 문서를 빌드합니다. - 런타임 버그 수정: 대상이 명확한 회귀 테스트를 추가하거나 실행한 다음, 변경된 파일에 필요한 검사를 수행합니다. - 공개 인터페이스, 구성 또는 언어 동작: 대상이 명확한 테스트를 실행하고 관련 문서나 예제를 업데이트합니다. 호환성 위험이 유의미하면 더 광범위한 패키지 테스트를 추가합니다. - 서버, 스트리밍, 추적, 작업 또는 생성 경로: 변경된 경로와 해당 대체 경로 또는 지원되지 않는 경로를 테스트합니다. - 패키징, 의존성 또는 잠금 파일 변경: 관련 설치 또는 패키징 검사를 실행하고 의존성 차이를 격리합니다. ### 범위와 격리 - 공식 전체 테스트 모음 명령에 무엇이 포함되는지 파악합니다. 가장 명백한 테스트 디렉터리만 포함된다고 가정하지 않습니다. - 실제 제공업체의 자격 증명을 제거하고 결정론적 대체 수단을 제공하는 테스트 진입점을 우선합니다. - 동일한 환경 보호 조치 아래에서 일반적인 병렬 실행과 결정론적 순차 실행을 비교해 격리 관련 불안정성을 진단합니다. - 테스트 실행기가 실제로 강제하지 않는 한 느린 실행 또는 순차 실행 마커는 참고 사항으로 취급합니다. - 편리한 대체 테스트 명령이 운영 자격 증명을 유지하거나 필수 테스트 경로를 우회할 수 있다면 사용하지 않습니다. ### 인계 증거 검토할 변경 사항은 인계 전에 공식 커밋 전 검사를 실행하여 서식, 라이선스, 타입 검사 결과가 안정적으로 유지되도록 합니다. 생략한 필수 검사가 있다면 해당 검사와 생략한 이유를 보고합니다. ## 중복 작업이 없는지 찾고 모든 리뷰 댓글에 답하기 공개 기여 활동을 승인된 작업과 추적 가능한 방식으로 연결하고 중복 작업을 피합니다. ### 구현 전 - 이슈의 분류와 배정이 완료되었으며, 사소하지 않은 작업에 대해 합의된 접근 방식이 뒷받침되는지 확인합니다. - 검토 가능한 형태의 작업을 준비하기 전에 읽기 전용 검색으로 이슈 논의, 해당 이슈를 참조하는 진행 중인 변경, 동일 영역의 진행 중인 변경을 확인합니다. - 진행 중인 변경이 이미 해당 작업을 다루고 있다면 중복 변경을 준비하지 않습니다. 접근 방식이 실질적으로 다르다면 이슈 논의에 사용할 초안에서 차이점을 설명합니다. - 탐색 작업의 경우 공개 변경 요청을 열지 말고 브랜치와 관련 파일을 설명하는 이슈 댓글 초안을 작성합니다. ### 제출 및 검토 - 리포지토리의 제목 및 커밋 규칙을 따릅니다. - 제목이나 커밋 메시지에 인공지능 표식을 추가하지 않고, 도구나 에이전트를 커밋 공동 작성자로 추가하지 않습니다. - 관리자에게 검토를 요청하기 전에 열려 있는 모든 검토 댓글을 처리하거나 답변합니다. - 정책에서 명시적으로 허용하지 않는 한 다른 검토자의 대화 스레드를 대신 해결하거나 자신의 변경에 준비 완료 레이블을 적용하지 않습니다. - 자동 및 사람 검토에서 나온 지적은 실제 코드 경로를 통해 확인해야 할 주장으로 취급하며, 자동으로 옳은 지시로 간주하지 않습니다. ## 사용자에게 보이는 동작이 바뀌면 문서 고치기 문서를 사용자가 볼 수 있는 동작과 일치하도록 유지하고, 제한적인 예제를 보편적으로 지원되는 것처럼 제시하지 않습니다. ### 문서화 의무 - 공개 인터페이스, 구성 구문, 예제, 설치 요구 사항 또는 기타 사용자가 볼 수 있는 동작을 변경할 때 관련 문서를 업데이트합니다. - 선택적 통합의 경우 선택 사항임을 명시하고, 필수 패키지나 기능 그룹을 밝히며, 값은 노출하지 않고 필요한 자격 증명의 유형을 나열하고, 통합 경로를 설명합니다. - 모델 또는 제공업체 예제에는 모델 유형, 라우팅 방식, 지원 모드, 알려진 제한 사항을 명시합니다. - 현재 사용 가능한 것으로 제시한 식별자가 일반적으로 제공되는지 공식 출처를 통해 확인합니다. - 단순히 문서를 업데이트하면서 배포되는 기본 매개변수를 변경하지 않습니다. ### 리팩터링과 생성된 콘텐츠 - 승인된 리팩터링에서는 미묘한 동작을 변경하기 전에 특성화 테스트를 추가하거나 업데이트합니다. - 기존 테스트가 리팩터링된 경로를 다루지 않는 경우에는 동작이 그대로 유지됨을 증명하는 데 사용한 동등성 검사를 보존합니다. - 생성된 문서나 생성된 산출물을 수동으로 편집하지 않습니다. 작업에서 재생성을 허용하는 경우에만 프로젝트 워크플로를 사용합니다. - 파일을 스테이징하거나 광범위한 검사를 실행하는 것으로 알려진 문서 빌더는 명시적으로 요청되고 관련 없는 변경과 격리된 경우가 아니면 실행하지 않습니다. ## 병합 기준점과 비교해 검토하고 확인한 것만 보고하기 완료된 변경을 올바른 기준점과 비교해 검토하고, 준비가 완료되었다고 선언하기 전에 모든 주장을 확인합니다. ### 검토 순서 1. 브랜치를 리포지토리에 설정된 병합 기준점과 비교합니다. 2. 구현과 이를 실제로 실행하는 테스트를 모두 점검합니다. 3. 구조화된 검토 전에 공식 서식, 린트, 라이선스, 타입 검사를 실행해 줄 위치가 바뀌지 않도록 합니다. 4. 구조화된 코드 검토를 수행하고 인증, 입력 처리, 역직렬화 또는 외부 호출 변경에는 보안 검토를 추가합니다. 5. 각 지적을 실제 실행 경로를 통해 확인합니다. 6. 확인된 지적을 수정하고 영향을 받은 검증을 다시 실행한 뒤, 확인된 문제가 남지 않을 때까지 검토를 반복합니다. ### 완료 기준 변경된 파일, 수행한 검증, 확인된 결과, 생략한 검사, 해결되지 않은 위험, 아직 필요한 사람의 조치를 보고합니다. 직접적인 증거 없이 검토 준비 완료, 승인, 호환성 또는 검증 성공을 주장하지 않습니다.