사용자 코드를 깨뜨리지 않고 공개 Go 라이브러리를 수정한다

## 코드를 바꾸기 전에 지원하는 Go 버전과 브랜치를 확인한다 정확성, 하위 호환성, 적용되는 외부 명세를 주요 인수 기준으로 취급한다. 코드를 변경하기 전에 다음을 파악한다. - 현재 개발 브랜치와 최신 안정 유지보수 브랜치 - 사용자가 이용할 수 있도록 지원하는 최소 Go 버전 - 저장소 개발에 필요한 더 최신의 Go 버전과 도구 체인 - 공개되고 호환성이 보장되는 API를 구성하는 패키지 - 가져올 수 있고 실제로 사용되지만 의미론적 버전 관리의 보장 대상은 아닌 내부 또는 실험적 패키지 “의미론적 버전 관리의 대상이 아님”을 “호환성을 깨뜨려도 안전함”으로 간주해서는 안 된다. 실제 사용자에게 지장을 줄 수 있는 동작 변경이나 API 변경을 명시한다. 저장소 정책에 따라 새 기능은 개발 브랜치로, 수정 사항은 적절한 안정 브랜치로 보낸다. 공개 패키지에서는 선언된 최소 Go 버전보다 새로운 표준 라이브러리 API와 언어 기능을 피한다. 지원되지 않는 기능이 사용자에게 도달하기 전에 일찍 실패하도록 호환성 검사를 빌드 안에서 실행 가능한 상태로 유지한다. ## 프로젝트의 도구로 검사와 테스트를 돌린다 익숙한 명령으로 대체하지 말고 프로젝트가 지정한 작업 실행기와 포매터를 사용한다. 기본 검증 대상에는 컴파일, 라이선스 검사, 형식 검사, 모듈 검사, lint, 빠른 테스트를 함께 포함해야 한다. 테스트를 두 단계로 유지한다. - 빠른 피드백을 위한 race 감지 기능이 활성화된 짧은 테스트 모음 - 저장소가 요구하는 서비스 의존성과 더 긴 시간 제한을 갖춘 전체 통합 테스트 모음 통합 테스트가 서버 상태를 공유한다면 전체 테스트 모음을 직렬로 실행해야 하며, 실행 시간을 줄일 목적만으로 병렬성을 높여서는 안 된다. 서비스 엔드포인트는 설정 가능하게 하되, 문서화된 로컬 기본값을 유지한다. 저수준 동작이 아키텍처에 따라 달라질 때는 여러 아키텍처를 대상으로 lint 또는 컴파일 검사를 실행한다. 특히 원자 접근을 사용할 때는 32-bit 대상을 검증한다. 원자적으로 접근하는 64-bit 필드는 구조체의 시작 부분에 두거나 형식이 지정된 원자 래퍼를 사용하는 등 안전하게 정렬되어야 한다. ## 오류 처리와 공개 API는 라이브러리의 기존 방식을 따른다 저장소에 확립된 패턴을 따른다. - `%w`를 사용해 오류를 문맥과 함께 감싸고, 메시지 텍스트를 대조하지 말고 `errors.Is` 또는 `errors.As`로 비교한다. - 차단될 수 있는 모든 공개 메서드의 첫 번째 인수로 `context.Context`를 사용하고, 호출자의 context에서 기한을 파생한다. 이와 경쟁하는 별도의 실시간 타이머를 만들지 않는다. - 키 순서가 중요한 명령이나 데이터에는 순서가 있는 문서 형식을 사용하고, 순서가 실제로 중요하지 않을 때만 map 계열 형식을 사용한다. 바이트 시퀀스를 기반으로 하는 저수준 표현은 타당한 근거가 있는 성능 핵심 경로에서만 사용한다. - 내보내는 식별자에는 약어 대신 완전한 단어를 사용하고, 모든 내보내는 식별자에 이름을 주어로 삼는 문서 주석을 추가하며, 새 옵션에는 프로젝트의 builder 또는 setter 패턴을 따른다. 현재의 패키지 배치와 마이그레이션 결정을 유지한다. 폐기된 가져오기 경로나 구식 공개 추상화를 되살려서는 안 된다. 명령 모니터링이나 진단 과정에서 인증 교환을 관찰할 수 있다면, 이벤트를 노출하기 전에 자격 증명을 처리하는 명령을 마스킹 정책에 추가한다. 기능별 네이티브 의존성과 빌드 태그는 설정 및 테스트 지침에 계속 명시해야 한다. ## 단위 테스트와 통합 테스트를 나누고, 변경에 필요한 테스트를 돌린다 단위 테스트는 구현 옆에 두고 통합 테스트는 저장소의 통합 테스트 영역에 둔다. 프로젝트의 assertion helper를 사용하고 부분 문자열 단언보다 `ErrorIs`와 같은 의미 기반 검사를 우선한다. 통합 동작에는 배포 설정, 장애 지점 주입, 이벤트 캡처를 지원하는 표준 토폴로지 인식 테스트 도구를 사용한다. 명세 fixture는 지정된 테스트 데이터 위치에 보관하고, 저장소를 복제한 뒤 필요한 submodule이나 fixture 원본을 초기화한다. 추적성이 중요할 때는 서술형 테스트 사례의 번호를 근거 명세의 번호와 맞춘다. 검토 전에 기본 검증 대상을 실행한다. 변경이 통합 동작이나 공유 서버 상태에 영향을 준다면 전체 테스트 모음을 직렬로 실행한다. 범위가 좁은 단위 테스트의 통과만으로는 여러 아키텍처, 호환성 또는 명세에 민감한 변경을 입증하기에 충분하지 않다. ## 테스트 결과와 호환성 영향을 pull request에 정리한다 커밋 메시지와 pull request 제목에 지정된 작업 항목 접두사를 사용한다. pull request에는 사용자에게 보이는 동작, 호환성에 미치는 영향, 테스트 근거, 브랜치 선택을 설명해야 한다. 변경에 맞는 근거를 추가한다. - 공개 API를 변경했다면 저장소의 API 보고서를 생성해 pull request에 포함한다. - 사용자에게 보이는 호환성 파괴 변경이라면 관련 마이그레이션 안내서를 갱신한다. - 명세 준수 작업이라면 구현이 충족하는 정확한 요구 사항을 인용한다. - 가져올 수 있는 실험적 패키지를 변경했다면 의미론적 버전 관리에서 요구하지 않더라도 호환성 파괴 영향을 명시한다. 로컬에서 빌드된다는 이유만으로 변경이 준비되었다고 제시해서는 안 된다. 준비 완료를 위해서는 저장소의 기본 검사와 직접 적용되는 모든 호환성, 통합, API, 명세 검사를 통과해야 한다.