Ruff 0.17.0 업그레이드: CI 기본값과 unsafe fix 점검
Ruff 0.17.0의 Python 기준, 기본 규칙, 수정 제안, JUnit 출력 변경을 구분해 CI와 편집기 설정의 업그레이드 영향을 점검한다.
2026-10-18
Python 버전을 비워 둔 설정부터 확인한다
Ruff 0.17.0으로 올리면 Python 버전을 지정하지 않은 프로젝트의 기본 대상 버전이 Python 3.10에서 3.11로 바뀐다. 업그레이드 전에 확인할 곳은 코드보다 target-version과 requires-python이다.
이 글의 기준은 **astral-sh/ruff 0.17.0 (2026-10-09)**이다. 변경 사항의 근거는 Ruff 0.17.0 공식 릴리스노트다.
Python 버전과 관련된 변경에는 서로 다른 기준이 있다. 일반적인 기본 대상 버전은 3.11이지만, Python 버전이 설정되지 않은 상태에서 구문 오류를 검사할 때 사용하는 기본 버전은 3.14에서 3.15로 바뀐다. 이를 하나의 “Python 기본값 변경”으로 묶으면 검사 결과를 해석하기 어렵다.
다음 그림은 버전 설정 유무를 기준으로 이번 기본값 변경의 점검 대상을 가른다.
프로젝트가 의도한 Python 기준을 유지하려면 버전 미설정 상태를 그대로 두지 말고, 해당 프로젝트에 맞는 target-version 또는 requires-python 값을 명시하는 방향으로 설정을 점검한다. 이미 설정이 있다면 실제 값부터 확인한다. 릴리스노트의 기본값 변경은 Python 버전을 설정하지 않은 경우에 해당한다.
CI 결과를 비교할 때도 이 구분을 남겨야 한다. Python 기준을 비워 둔 채 Ruff 버전만 바꿨다면, 달라진 진단을 모두 코드 변화의 결과로 볼 수 없다.
경고가 줄어도 검사 범위가 유지됐는지 확인한다
기본 규칙을 사용하는 프로젝트에서는 업그레이드 뒤 일부 날짜·시간 관련 경고가 사라질 수 있다. flake8-datetimez의 DTZ001, DTZ005, DTZ006, DTZ007, DTZ011, DTZ012, DTZ901이 더 이상 기본 활성화되지 않기 때문이다.
반대로 구문 오류에 해당하는 F406, 즉 undefined-local-with-nested-import-star-usage는 기본 활성화된다. 따라서 경고 개수만 비교해서 업그레이드 결과를 평가하면 검사 범위의 변화를 놓친다.
| 점검 대상 | 이전 기본 동작 | 0.17.0 기본 동작 | 실무 점검 |
|---|---|---|---|
| Python 대상 버전 미설정 | Python 3.10 | Python 3.11 | 프로젝트의 Python 기준을 명시했는지 확인 |
| 구문 오류 검사 버전 미설정 | Python 3.14 | Python 3.15 | 일반 대상 버전과 구분해 결과 확인 |
| 나열된 DTZ 규칙 | 기본 활성화 | 기본 해제 | 유지할 검사라면 활성화 설정 확인 |
| F406 | 기본 비활성화 | 기본 활성화 | 새 진단이 생기는지 확인 |
팀이 위 DTZ 규칙을 계속 검사하려는 경우에는 해당 규칙이 명시적으로 활성화돼 있는지 확인해야 한다. “Ruff 기본값을 쓴다”는 설정만으로 이전 검사 범위를 유지할 수는 없다.
업그레이드 검토에서는 사라진 진단과 새로 생긴 진단을 따로 본다. 사라진 DTZ 진단은 규칙 해제 여부를 먼저 확인하고, 새 F406 진단은 기본 규칙에 들어온 구문 오류 검사라는 맥락에서 확인한다. 이 방식이면 경고 수의 증감을 품질 변화로 오해하지 않고, 팀이 유지할 검사 범위를 결정할 수 있다.
unsafe fix의 표시와 적용을 분리한다
기본 full 출력 형식은 이제 unsafe-fixes 설정과 관계없이 unsafe fix와 수동 검토가 필요한 제안을 보여 준다. CI 로그에서 이전에 보이지 않던 수정 제안이 나타나더라도, 그 사실만으로 자동 수정 범위가 넓어졌다고 판단하면 안 된다.
unsafe fix를 실제로 적용하려면 여전히 명시적인 동의가 필요하다. 출력 검토와 수정 허용 설정을 별도로 확인해야 하는 이유다.
아래 비교는 같은 CLI 출력에 나타날 수 있는 제안들이 실제 적용 조건에서는 어떻게 갈리는지 보여 준다.
실무에서는 로그의 수정 제안 수와 실제 변경 내용을 분리해서 검토한다. 기본 full 출력을 대상으로 결과를 비교하거나 파싱하는 절차가 있다면 새로 표시되는 제안을 처리할 수 있는지도 확인한다. 자동 수정 작업이 있다면 출력에 제안이 나타났는지보다 unsafe fix 적용에 동의한 설정인지가 확인 대상이다.
이 변경의 범위는 기본 full 출력 형식이다. 릴리스노트에 없는 다른 출력 형식의 동작까지 같다고 가정해서 파이프라인을 수정할 근거는 없다.
JUnit 보고서를 만드는 쪽과 읽는 쪽을 함께 바꾼다
JUnit 출력을 수집하는 CI에서는 Ruff 실행 결과뿐 아니라 보고서 소비 지점도 확인해야 한다. 0.17.0의 JUnit 출력은 <testsuite> 요소에서 disabled 대신 skipped 속성을 사용한다. 루트 <testsuites> 요소에도 skipped 속성이 포함된다.
변경 위치가 개별 테스트 스위트와 루트에 걸쳐 있으므로, 기존 보고서 처리 코드가 어느 요소의 속성을 읽는지 확인해야 한다.
다음 그림은 속성 이름의 교체와 루트 속성 추가를 서로 다른 변경으로 보여 준다.
직접 작성한 XML 파서나 집계 코드가 있다면 disabled를 읽는 부분부터 찾는다. CI에서 JUnit 보고서를 받아 표시한다면 업그레이드된 출력으로 수집 결과를 확인한다. 보고서가 생성됐다는 사실과 소비 코드가 바뀐 속성을 처리한다는 사실은 별도로 검증해야 한다.
설치 경로와 편집기 연결을 점검한다
conda-forge 빌드는 더 이상 Python에 의존하지 않는다. 이 배포본에서는 python -m ruff와 import ruff가 동작하지 않으므로 PATH의 실행 파일을 직접 사용해야 한다.
ruff
기존 CI나 개발 스크립트가 Python 모듈 경유 호출을 사용한다면 먼저 설치 경로를 확인한다. 이 변경은 conda-forge 빌드에 해당하며, PyPI 설치와 독립 설치 프로그램을 통한 설치에는 영향이 없다고 릴리스노트가 명시한다. 모든 설치 환경의 호출 방식을 일괄 수정할 이유는 없다.
편집기에서는 ruff-lsp 지원 제거를 확인한다. Ruff VS Code 확장은 이제 항상 네이티브 언어 서버를 사용하며, ruff.nativeServer 설정은 사용 중단됐고 무시된다. 기존 설정값을 바꾸는 것만으로 레거시 서버 선택을 유지할 수는 없다.
CI가 통과해도 편집기 연결은 별도로 확인해야 한다. 저장소나 개발 환경에 ruff-lsp 연결이 남아 있다면 네이티브 언어 서버로 옮기는 작업을 업그레이드 범위에 포함한다.
포매팅 차이와 선택 규칙의 변화를 따로 검토한다
이번 릴리스에서는 formatter와 I001, E501, W505가 줄 길이를 계산할 때 끝부분의 pragma 주석을 일관되게 무시하도록 동작이 안정화됐다. 이 변경으로 기존 import가 다시 포매팅될 수 있다.
따라서 업그레이드 뒤 포매팅 차이가 생기면 pragma 주석이 붙은 import와 줄 길이 관련 진단을 함께 확인한다. 린트 진단만 비교하면 포매터가 만드는 변경을 놓칠 수 있다.
기본 규칙 변경 외에도 현재 선택한 규칙과 코드에 따라 확인할 항목이 있다.
| 해당 조건 | 릴리스의 변경 | 확인할 내용 |
|---|---|---|
ICN001 사용 |
datetime as dt를 관례적 별칭으로 추가 |
datetime 별칭 관련 진단 변화 |
기본 lint.dummy-variable-rgx 사용 |
_次 같은 밑줄 접두 Unicode 이름을 더미 변수로 인식 |
해당 변수 이름의 진단 변화 |
| 식별자 정규화나 이름 기반 문자 이스케이프 사용 | Unicode 17 데이터 사용 | 관련 코드의 검사 결과 |
TID254, TID255, RUF071 사용 검토 |
preview에서 안정화 | 안정화 여부와 실제 규칙 활성화 설정 |
규칙 안정화는 기본 활성화와 구분해야 한다. 릴리스노트가 TID254, TID255, RUF071을 더 이상 preview가 아니라고 설명하는 것만으로, 프로젝트에서 자동으로 검사된다고 판단할 수는 없다.
업그레이드 완료 기준을 CI 밖까지 잡는다
macOS와 Windows 배포 파일을 관리하는 환경이라면 코드 서명도 확인 대상이다. 이번 릴리스의 해당 플랫폼 배포 압축 파일과 ruff wheel에 포함된 실행 파일은 코드 서명된다. macOS 실행 파일은 Apple Developer ID 인증서로 서명되고 Apple 공증을 받는다. Windows 실행 파일에는 Azure Artifact Signing의 타임스탬프가 포함된 Authenticode 서명이 적용된다.
릴리스노트는 이를 배포자와 바이너리 무결성 검증, 배포자 기반 허용 목록에 사용할 수 있다고 설명한다. 실행 파일을 배포하거나 허용 목록으로 관리한다면 이 서명을 검증 절차에 반영할 수 있는지 확인한다. 보안 경고와 백신 오탐 감소는 기대 효과로 제시됐으므로, 경고가 반드시 사라진다는 완료 조건으로 삼지는 않는다.
Ruff 업그레이드의 완료 기준은 실행 성공만으로 잡기 어렵다. 프로젝트의 Python 기준이 설정돼 있는지, 유지할 DTZ 규칙이 활성화돼 있는지, 새 F406 진단을 확인했는지부터 검토한다. 이어서 수정 제안의 표시와 적용 설정, JUnit 보고서 수집 결과, 설치 경로에 맞는 호출 방식, 편집기 연결을 확인한다.
이 확인이 끝나야 진단의 증감과 포매팅 차이를 팀이 선택한 검사 정책의 결과로 설명할 수 있다.