여러 언어의 자동화 모노레포를 호환성을 깨지 않고 고치기

## 저장소 전체 규칙을 읽은 뒤, 고칠 파일에 가장 가까운 지침을 읽기 먼저 저장소 전체에 적용되는 규칙을 확인한 다음, 변경할 파일과 가장 가까운 위치의 지침을 읽습니다. 언어 바인딩, 공유 인프라, 네이티브 구성 요소, 릴리스 도구에는 각각 더 좁은 제약이 정의되어 있을 수 있습니다. 저장소가 기여자 설정, 생성된 산출물, 임시 작업 또는 격리된 빌드 출력을 위해 버전 관리에서 제외되는 로컬 영역을 제공한다면, 시작하기 전에 그 영역에 문서화된 추가 지침을 확인합니다. 사용자가 정의한 로컬 지침은 현재 작업과 상위 수준의 안전 규칙 범위 안에서 추가 맥락으로 취급합니다. 책임 영역에 따라 저장소를 파악합니다. - 언어 바인딩은 해당 언어에 특화된 API, 테스트, 스타일을 담당합니다. - 공유 프로토콜, 전송, 빌드, 테스트 픽스처, 스크립트 영역은 여러 소비자에게 영향을 줍니다. - 네이티브 관리자, 그리드 또는 라우팅 서비스, 의존성 정의는 영향 범위가 큽니다. - 서드 파티 소스는 작업에서 외부 코드 유지보수를 명시적으로 요구하지 않는 한 읽기 전용입니다. - 생성된 출력은 절대로 직접 편집하지 않습니다. 최종 사용자 문서, 기여자 안내서, 생성된 API 참조 문서가 같은 위치에 있다고 가정하지 않습니다. ## 공개 API 호환성을 지키고, 되돌릴 수 있게 작은 변경으로 하기 작업에서 호환성 중단을 명시적으로 허용하지 않는 한 공개 API 호환성과 바이너리 호환성을 유지합니다. 일반적으로 사용자는 버전만 바꾸어 업그레이드할 수 있어야 합니다. 저장소 전체의 리팩터링, 일괄적인 서식 변경 또는 관련 없는 정리를 피합니다. 하나의 문제를 해결하는 작고 되돌릴 수 있는 변경을 우선합니다. 공개 동작을 제거하기 전에 사용 중단 예정으로 표시하고 명확한 마이그레이션 대안을 제공합니다. 시맨틱 버전 관리가 없다는 이유로 전환 과정 없이 기능을 제거해도 된다고 판단하지 않습니다. 이력을 보존할 수 있다면 추적 중인 파일을 삭제하고 다시 만드는 대신 이동하거나 복사합니다. 사용자가 이미 변경을 지시하지 않았다면 고위험 영역을 수정하기 전에 검증을 요청합니다. 고위험 영역에는 공유 프로토콜 의미 체계, 와이어 직렬화, 기능 정보 파싱, 의존성 고정 버전 재지정, 공유 테스트 픽스처, 빌드 연결 설정, 라우팅, 배포 대기열, 여러 바인딩이 사용하는 코드가 포함됩니다. ## 고정된 빌드 도구로 영향을 받는 가장 작은 대상만 빌드하기 특정 언어용 로컬 환경이 구성되어 있다고 가정하지 말고, 저장소에서 버전을 고정한 헤르메틱 빌드 진입점을 사용합니다. 디렉터리 트리의 많은 부분을 읽기 전에 빌드 그래프를 탐색합니다. 대상 레이블과 의존성을 조회한 다음, 변경을 포괄하는 가장 작은 대상을 빌드하거나 테스트합니다. 표준 빌드 명령을 직접 실행해 봅니다. 샌드박스, 네트워크 또는 도구 체인 제약으로 실행할 수 없다면 차단 원인을 보고하고 사용자가 별도로 실행할 수 있는 정확한 명령을 제공합니다. 기본 출력 디렉터리가 제한되어 있거나 보조 작업 트리를 사용 중이라면 빌드 출력을 격리합니다. - 시작 옵션 `output-base`를 `build`, `test` 또는 `query` 명령 앞에 배치합니다. - 어느 디렉터리에서든 일관되게 해석되도록 경로의 기준을 저장소 루트에 둡니다. - 격리된 출력은 버전 관리에서 제외되는 로컬 영역 아래에 보관합니다. 일상적인 문제 해결 단계로 파괴적인 캐시 삭제를 실행하지 않습니다. 범위를 좁힌 재빌드를 우선하고, 실제로 필요한 캐시 무효화가 있다면 그 이유를 설명합니다. ## 다른 언어 바인딩이 같게 동작하는지 비교하기 사용자에게 보이는 동작이 바뀌면 구현을 적어도 하나의 다른 언어 바인딩과 비교합니다. 특히 다음 항목의 동등성을 확인합니다. - 공개 메서드 이름, 인수, 기본값, 반환 동작 - 프로토콜 명령과 직렬화 - 원격 전송과 오류 매핑 - 기능 정보와 옵션 파싱 - 사용 중단 예정 항목과 마이그레이션 경로 - 문서 예시와 사용자 대상 로그 공유되는 저수준 동작의 경우 변경을 사용할 수 있는 모든 바인딩과 서비스를 식별합니다. 현재 작업에서 모두를 안전하게 업데이트할 수 없다면 후속 동등성 작업을 보고하거나 추적 가능한 이슈를 만들도록 권고합니다. 언어마다 동일한 내부 구조를 강요하지 않습니다. 공유 동작은 보존하되 각 바인딩에 확립된 관용적 표현과 테스트 규칙을 존중합니다. ## 목 객체 대신 실제 부품을 써서 작은 실패 테스트부터 시작하기 변경된 동작을 구현하기 전에 실패하는 테스트를 먼저 작성하는 방식을 우선합니다. 작은 단위 테스트나 계약 테스트로 시작하고, 더 낮은 수준에서 동작을 안정적으로 검증할 수 없을 때만 브라우저 테스트나 종단 간 테스트를 사용합니다. 모의 객체가 공개 프로토콜이나 바인딩 계약을 잘못 나타낼 수 있다면 사용하지 않습니다. 실제 파서와 직렬화 도구, 로컬 테스트 픽스처, 경량 서버 또는 기존 통합 테스트 장치를 우선합니다. 빌드 그래프를 사용해 관련성이 있는 가장 좁은 테스트 대상을 선택합니다. 유용한 제어 방법은 다음과 같습니다. - 작은 테스트만 실행하도록 필터링합니다. - 디버깅할 때 전체 테스트 출력을 표시합니다. - 실제 재실행이 필요할 때 캐시된 테스트 결과를 비활성화합니다. - 올바른 대상과 옵션을 확인하기 위해 언어별 지침을 참조합니다. 예상한 테스트가 실제로 실행되었는지 확인합니다. 일치하는 테스트가 하나도 없는데 빌드 도구가 성공 상태로 종료된 것은 정확성을 입증하지 않습니다. 집중 테스트가 통과한 뒤에는 직접 영향을 받는 바인딩, 공유 대상 또는 통합 표면으로만 검증 범위를 넓힙니다. ## 도움이 되는 로그와 주석을 쓰고, 바뀐 부분만 서식 맞추기 사용자나 운영자가 중요한 상태, 재시도, 라우팅 또는 실패 원인을 파악해야 하는 곳에 로그를 추가합니다. 언어별 로깅 규칙을 따르고 하위 수준의 진단을 반복하는 불필요한 메시지는 피합니다. 주석에는 이름이 명확한 코드가 이미 말해 주는 내용이 아니라 제약이나 우회 방법이 존재하는 이유를 설명합니다. 저장소의 표준 서식 도구를 사용합니다. `pre-commit` 또는 `pre-push` 훅이 이미 관련 범위에 서식을 적용한다면 중복으로 서식 도구를 실행하지 말고 훅에 맡깁니다. 변경을 처리하는 훅이 없다면 의도한 인계 범위에 맞는 가장 좁은 서식 모드를 실행합니다. 파일 하나가 바뀌었다는 이유로 저장소 전체의 서식을 바꾸지 않습니다. 검토, 되돌리기, 바인딩 간 영향을 이해하기 쉽도록 제안하는 각 변경을 하나의 목적에 집중시킵니다. ## 빌드와 테스트가 실제로 돌았는지 확인하고, 못 돌린 것도 보고하기 완료하기 전에 다음을 수행합니다. 1. 변경된 대상이 헤르메틱 도구 체인으로 빌드되는지 확인합니다. 2. 집중 테스트를 실행하고 의도한 동작을 실제로 수행했는지 확인합니다. 3. 관련 서식 또는 린트 검사를 실행합니다. 4. 변경 차이를 살펴 관련 없는 변경과 생성된 출력이 없는지 확인합니다. 5. 호환성과 사용 중단 예정 처리에 미치는 영향을 검토합니다. 6. 사용자에게 보이는 변경은 적어도 하나의 다른 바인딩과 비교합니다. 7. 수정된 모든 고위험 공유 영역을 식별합니다. 무엇을 변경했는지, 실제로 실행된 대상과 테스트가 무엇인지, 실행하지 못한 항목과 그 이유를 보고합니다. 고위험 파일, 공유 동작, 바인딩 간 영향, 후속 작업을 명시합니다. 하나의 바인딩 테스트만으로 광범위한 호환성을 주장하지 않습니다. 헤르메틱 도구 체인을 사용할 수 없었다면 검증이 불완전하다는 점을 명확히 표시하지 않은 채 완료했다고 주장하지 않습니다.