크로스 플랫폼 CLI 다운로더에 도구를 추가하고 바이너리마다 확인하기

## 도구가 정적 바이너리를 제공하는지 확인하고 대상 플랫폼 정하기 직접 실행 가능한 정적 바이너리로 배포되는 명령줄 도구를 추가할 때 이 워크플로를 사용하세요. 시스템 패키지, 컨테이너 이미지 추출, 클러스터 애드온, 런타임 관리 애플리케이션은 각각의 설치 경로로 보내세요. 코드를 변경하기 전에 제안된 도구에 미리 컴파일된 릴리스 자산이 있는지 확인하세요. 인터프리터, 패키지 관리자, 설치 스크립트 또는 선언되지 않은 런타임 종속성이 필요한 패키지는 거부하세요. 프로젝트에서 더 넓은 일괄 변경을 명시적으로 허용하지 않는 한 기여가 하나의 도구만 변경하는지 확인하세요. 프로젝트별 설계 또는 이슈 승인이 관문으로 존재한다면 구현 전에 해당 승인을 요구하세요. 저장소의 명명 규칙에 따라 범위가 명확한 브랜치를 만드세요. 설치 프로그램 명령, 도구의 공개 이름, 원본 프로젝트의 소유자와 저장소를 식별하세요. 설치 프로그램이 지원해야 하는 모든 플랫폼 조합을 나열하세요. 프로젝트에서 다른 매트릭스를 정의하지 않는 한 다음 기준 대상을 사용하세요. - x86-64 기반 Linux. - ARM64 기반 Linux. - x86-64 기반 macOS. - ARM64 기반 macOS. - x86-64 기반 Windows. 설치 프로그램에 명시적으로 포함되지 않은 한 32비트 x86 또는 ARMv6 지원을 주장하지 마세요. 다른 플랫폼의 아티팩트로 몰래 대체하지 말고 사용할 수 없는 조합을 기록하세요. ## 코딩 전에 운영체제와 아키텍처별 정확한 배포 파일 이름 조사하기 다운로드 템플릿을 작성하기 전에 원본 프로젝트의 최신 안정 릴리스를 검사하세요. Location 헤더를 통해 버전 태그를 확인할 수 있도록 원본 프로젝트의 최신 릴리스 엔드포인트에는 리디렉션만 요청하는 방식을 우선하세요. 태그 자체가 필요한 결과라면 리디렉션을 따라가지 마세요. 해당 태그의 전체 자산 목록이나 그와 동등한 권위 있는 릴리스 페이지를 검사하세요. 동등한 공개 릴리스 메타데이터를 사용할 수 있다면 요청 제한이 있는 API를 소비하지 마세요. 게시된 모든 파일 이름, 아카이브 형식, 운영 체제, 아키텍처를 열거하세요. amd64와 x86_64, arm64와 aarch64 같은 구분을 포함해 원본 프로젝트의 용어를 정확히 유지하세요. 예상되는 각 대상에 대해 다음을 기록하세요. - 자산의 존재 여부. - 정확한 자산 파일 이름. - 아카이브 유형이 있다면 해당 유형. - 아카이브 내부의 바이너리 이름이 다르다면 해당 이름. - 호환성을 바꾸는 libc 또는 툴체인 변형. 프로젝트가 지원하고 선택이 적절하다면 musl 같은 이식 가능한 정적 변형을 우선하세요. unknown 같은 용어가 포함된 Rust 파일 이름도 원본 프로젝트의 릴리스와 일치한다면 유효한 것으로 취급하세요. 수집한 매트릭스를 템플릿, 테스트, 풀 리퀘스트 증거의 기준 정보로 사용하세요. ## 플랫폼마다 실제 다운로드 URL을 연결하고 다른 파일로 대신하지 않기 설치 프로그램의 기존 정의 구조를 통해 도구를 추가하고 근처의 정상 작동 예시를 따르세요. 필수 식별 필드인 도구 이름, 원본 프로젝트 소유자, 저장소, 간단한 설명을 제공하세요. 릴리스 자산 자체가 실행 파일인 일반 바이너리에는 바이너리 파일 이름 템플릿을 사용하세요. 자산 위치에 사용자 지정 경로 논리가 필요하면 전체 URL 템플릿을 사용하세요. 지원되는 각 운영 체제와 아키텍처를 실제 원본 파일 이름에 매핑하세요. 설치 프로그램의 아키텍처 상수와 원본 파일 이름의 용어를 분리해서 유지하세요. 런타임의 운영 체제 표현과 일치하는 명시적인 Windows 감지를 사용하세요. 지원되는 아카이브 형식은 설치 프로그램의 압축 해제 기능과 일치해야 합니다. 일반적으로 허용되는 형식에는 tar.gz, tgz, zip, bz2, tar.xz가 있습니다. 플랫폼 조합을 사용할 수 없다면 생성된 URL은 리소스 없음 응답처럼 명확하게 실패해야 합니다. 절대로 Linux 아티팩트, 다른 아키텍처 또는 다른 도구로 대체되어서는 안 됩니다. 접두사가 붙은 태그와 숫자 버전을 모두 사용할 때는 특히 버전 태그 변환을 명시적으로 유지하세요. 운영 체제, 아키텍처, 이름, 버전, 소유자, 저장소에 기존 템플릿 변수를 사용하세요. 설치 프로그램이 버전 치환을 지원한다면 프로덕션 정의에 현재 버전을 하드코딩하지 마세요. 테스트에 의존하기 전에 매트릭스의 모든 행에 대한 최종 URL을 검토하세요. ## 아카이브 이름과 그 안의 실행 파일 이름을 따로 지정하기 릴리스 자산 이름과 아카이브 내부 실행 파일 이름을 별개의 사실로 취급하세요. 아카이브에 플랫폼 접미사가 붙은 실행 파일이 있다면 다음 두 가지를 모두 정의하세요. - 확장자를 포함한 다운로드용 아카이브 이름을 지정하는 URL 템플릿. - 아카이브 확장자 없이 추출된 실행 파일 이름을 지정하는 바이너리 템플릿. 확장자가 포함된 아카이브 파일 이름만 바이너리 템플릿에 넣지 마세요. 많은 압축 해제 도구가 추출된 파일을 찾는 데 바이너리 템플릿을 사용합니다. 이 필드의 아카이브 확장자는 일반 도구 이름을 사용하는 대체 경로를 유발할 수 있습니다. 아카이브에 플랫폼별 바이너리 이름이 들어 있으면 그 대체 경로는 실패합니다. 압축되지 않은 일반 실행 파일에는 대개 바이너리 템플릿만으로 충분합니다. 파일 이름만 보고 추측하지 말고 아카이브를 검사하여 이 차이를 확인하세요. 아카이브가 실행 파일에 디렉터리 접두사를 추가하는지 확인하세요. Windows 실행 파일의 매핑과 추출 모두에 exe 접미사가 필요한지 확인하세요. 체크섬, 서명, 실행 권한 처리를 기존 설치 프로그램과 일관되게 유지하세요. 추출 과정에서 파일 누락이 보고되면 다음 세 이름을 비교하세요. - 다운로드한 자산. - 추출된 아카이브 구성원. - 설치 프로그램이 요청한 이름. 광범위한 대체 경로를 추가하지 말고 정의 경계에서 매핑을 수정하세요. ## 고정 버전으로 모든 플랫폼의 다운로드 URL 테스트하기 기존 다운로더 테스트 옆에 범위가 명확한 단위 테스트를 추가하세요. 원본 프로젝트의 고정된 버전을 사용하고, latest를 대상으로 URL 생성을 절대로 테스트하지 마세요. 게시되고 지원되는 운영 체제와 아키텍처의 모든 조합마다 하나의 사례를 만드세요. 소유자, 저장소, 태그, 파일 이름, 구분자, 아카이브 확장자를 포함한 전체 예상 URL을 단언하세요. 플랫폼별 아키텍처 별칭을 원본 프로젝트에서 게시한 그대로 포함하세요. 특수한 버전 변환과 Windows 접미사가 있다면 테스트하세요. 사용할 수 없는 조합은 프레임워크가 해당 사례를 지원할 때 설치 프로그램이 의도한 실패 동작을 테스트하세요. 변경 가능한 릴리스 메타데이터와 독립적으로 테스트를 유지하세요. 구현 전에 수집한 것과 동일한 자산 매트릭스를 사용하세요. 먼저 대상 패키지 테스트를 실행하세요. 그런 다음 해당되는 경우 프로젝트에서 요구하는 더 광범위한 테스트 대상을 실행하세요. URL 테스트 통과는 문자열 구성만 증명하며, 다운로드한 파일이 올바른 바이너리라는 사실은 증명하지 않습니다. ## 플랫폼마다 바이너리를 내려받아 형식과 아키텍처 확인하기 크로스 플랫폼 검증 전에 설치 프로그램을 빌드하세요. 먼저 재정의 플래그 없이 현재 플랫폼의 아티팩트를 다운로드하세요. 결과 파일을 검사하여 HTML 오류 페이지, 실행 파일로 오인된 압축 데이터, 빈 파일을 찾아내세요. 도구에 대해 저장소의 플랫폼 매트릭스 검증 스크립트를 실행하세요. 테스트를 실행하는 시스템뿐 아니라 지원되는 모든 조합을 검증하세요. 파일 식별 도구나 동등한 바이너리 파서를 사용하여 형식과 아키텍처를 확인하세요. 일반적으로 예상되는 증거에는 다음이 포함됩니다. - Linux x86-64용 64비트 ELF 실행 파일로서 x86-64 대상. - Linux ARM64용 64비트 ELF 실행 파일로서 AArch64 대상. - macOS x86-64용 64비트 Mach-O 실행 파일로서 x86-64 대상. - macOS ARM64용 64비트 Mach-O 실행 파일로서 ARM64 대상. - Windows x86-64용 PE32+ 콘솔 실행 파일로서 x86-64 대상. 템플릿이 잘못된 플랫폼을 다운로드할 수 있으므로 성공한 HTTP 응답만으로는 충분하지 않습니다. 내부 실행 파일이 잘못된 아키텍처를 대상으로 할 수 있으므로 성공한 압축 해제만으로도 충분하지 않습니다. 실패나 경고를 편집해 없애지 말고 전체 매트릭스 출력을 캡처하세요. 원본 프로젝트에서 대상을 사용할 수 없다면 호환되지 않는 바이너리를 제공하는 대신 설치 프로그램이 해당 대상에 대해 실패하는지 검증하세요. 문서화나 승인 전에 모든 불일치를 해결하세요. ## CLI 카탈로그를 다시 생성하고 PR에 확인 결과 적기 CLI 카탈로그를 다시 생성하는 저장소의 문서화된 절차를 따르세요. 행을 수동으로 만들어 내지 말고 설치 프로그램에서 카탈로그를 생성하세요. 안전한 교체에 필요할 때만 임시 작업 공간 파일을 사용하세요. 카탈로그의 정확한 시작 및 종료 마커를 유지하세요. 해당 마커 사이의 생성된 표 내용과 관련 도구 개수만 교체하세요. 주변 설명이나 관련 없는 항목을 제거하지 마세요. 새 도구가 예상 설명과 함께 한 번만 나타나는지 확인하세요. 업데이트 후 임시 생성 파일을 삭제하세요. 다음 내용을 명시하는 풀 리퀘스트 설명을 준비하세요. - 사용 가능한 플랫폼 조합과 사용할 수 없는 플랫폼 조합. - 사용한 공식 릴리스 태그와 명명 패턴. - 바이너리 형식을 포함한 전체 플랫폼 검증 출력. - 해당되는 경우 필수 엔드 투 엔드 테스트 또는 더 광범위한 테스트 출력. 모든 커밋에 저장소에서 요구하는 서명이 포함되도록 하세요. 명령과 고정 버전을 명시하여 증거를 재현 가능하게 유지하세요. 누락된 플랫폼, 실패한 다운로드 또는 아키텍처 불일치를 요약에서 숨기지 마세요. ## 변경을 검토하고 다운로드나 압축 해제 실패의 원인 찾기 적격성, 매핑, 테스트, 문서, 증거를 별개의 관문으로 검토하세요. 도구가 정적 바이너리이고 변경이 승인된 범위로 제한되는지 확인하세요. 필수 식별 필드를 확인하고 유효한 다운로드 매핑이 하나 이상 있는지 확인하세요. 모든 템플릿 분기를 공식 자산 매트릭스와 비교하세요. 지원되지 않는 조합이 다른 플랫폼의 바이너리를 받을 수 없는지 검증하세요. 단위 테스트가 고정 버전을 사용하고 지원되는 모든 대상을 포함하는지 확인하세요. 승인 전에 주장하는 모든 대상에 대한 바이너리 형식 증거를 요구하세요. 생성된 문서에 도구가 포함되고 경계 마커가 유지되는지 확인하세요. 정확한 원본 파일 이름과 태그 변환을 비교하여 URL 불일치를 조사하세요. 운영 체제 분기와 아키텍처 분기를 독립적으로 추적하여 잘못된 아키텍처를 조사하세요. 아카이브 이름, 아카이브 구성원, 구성된 내부 바이너리 이름을 비교하여 추출 실패를 조사하세요. 프로젝트가 실제로 자체 완결형 정적 바이너리를 제공하는지 다시 검토하여 런타임 실패를 조사하세요. 누락된 원본 자산을 호환되지 않는 대체물로 우회하지 마세요. 원본 프로젝트에 실제로 누락된 항목을 풀 리퀘스트에 문서화하세요. 코드, 테스트, 다운로드한 아티팩트, 문서, 보고된 증거가 모두 일치할 때만 승인하세요.