의존성 안전하게 업그레이드하기
목표: 하나의 의존성(또는 하나의 밀접하게 결합된 그룹)을 사전에 중단 사항을 파악하여 업그레이드하고, 사후에 발견되는 문제를 방지합니다.
계획
- 현재 상태를 정확히 파악합니다. 설치된 버전(매니페스트가 아닌 락파일)과 대상 버전을 확인합니다. 사용자가 "latest"라고 한 경우 패키지 매니저로 조회합니다 (
npm view <pkg> version,pip index versions <pkg>,cargo search등) 하고 버전 번호를 명시합니다. - 깨끗한 작업 트리에서 기준을 기록합니다. 설치, 빌드, 테스트, 린트, 타입 검사를 실행합니다. 기존에 실패한 항목이 있다면 업그레이드 탓으로 돌리지 않도록 기록합니다.
- 실제 릴리스 노트를 읽습니다. 현재 버전과 대상 버전 사이의 모든 버전에 대한 체인지로그, 릴리스 노트 또는 마이그레이션 가이드를 엽니다. 다음 항목을 추출합니다: 중대한 변경 사항, 제거되거나 이름이 변경된 API, 새로운 최소 런타임 버전, 변경된 기본값, 폐기 예정 기능. 각 항목에 대해 소스 링크를 인용합니다. 릴리스 노트를 찾을 수 없는 경우 그 사실을 말하고 해당 업그레이드를 더 높은 위험도로 처리합니다.
- 영향을 매핑합니다.
rg를 사용하여 제거되거나 이름이 변경되거나 변경된 각 API에 대해 코드베이스를 검색합니다. 편집 전에 영향을 받는 파일 목록을 작성합니다.
실행
- 이 의존성(및 필수 피어 의존성)만 업그레이드합니다. 포괄적인 "전체 업데이트"를 실행하지 마십시오.
- 수동이 아닌 프로젝트의 패키지 매니저를 사용하여 매니페스트와 락파일을 업데이트합니다.
- 릴리스 노트에 필요한 코드 변경을 가장 작은 것부터 적용합니다. 대체 형식이 동등한 경우 폐기된 사용법을 대체합니다.
- 설치, 빌드, 테스트, 린트 및 타입 검사를 다시 실행합니다. 기준과 비교합니다.
- 주요 버전의 경우 가능하다면 애플리케이션 또는 주요 예제 경로도 실행하고, 번들 크기, 시작 경고 및 폐기 경고를 확인합니다.
- 업그레이드에 최소 런타임 또는 피어 버전 범프가 필요한 경우 변경 전에 중단하고 문의합니다.
보고
업그레이드: <pkg> <from> -> <to>
출처: <체인지로그 링크>
적용된 중대한 변경 사항: <파일 참조와 함께 목록>
변경 사항: <요약>
검증: <명령어, 기준 vs 후>
경고 또는 후속 조치: <폐기, 건너뛴 항목, 위험>
롤백: <파일> 되돌리기, 또는 `git revert <commit>`
규칙
- 업그레이드와 리팩터링을 동시에 수행하지 마십시오.
- 실패하는 테스트를 절대 건너뛰거나 버전 범위를 느슨하게 하여 문제를 숨기지 마십시오.
- 보안 수정 사항: 공식 권고 또는 릴리스 노트에서 확인한 경우에만 해당 업그레이드가 해결하는 권고를 언급합니다.
- 전이 의존성이 충돌을 강제하는 경우 충돌 출력을 보여주고 맹목적으로 재정의하기보다 옵션을 제안합니다.