byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

UV 문서 · Reference

재현 가능한 예시

Reproducible examples · 원문: docs.astral.sh/uv/reference/troubleshooting/reproducible-examples/

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

재현 가능한 예시가 중요한 이유

"최소 재현 가능한 예시(MRE, Minimal Reproducible Example)는 버그 수정에 필수적입니다." 메인테이너가 문제를 재현하는 데 사용할 수 있는 예시가 없으면 디버깅하거나 수정 시점을 확인할 수 없습니다. 불필요한 내용을 포함하는 비대한 예시는 근본 원인을 파악하는 데 필요한 시간을 크게 늘립니다.

재현 가능한 예시 작성 방법

효과적인 재현 가능한 예시는 다른 사람이 문제를 재현하기 위한 완전한 컨텍스트를 제공합니다:

불필요한 의존성, 구성, 파일을 모두 제거하여 재현을 최소화합니다. 공유 전에 항상 재현을 테스트하고 상세 로그를 포함하세요. 출력이 시스템마다 의미 있게 다를 수 있습니다. Stack Overflow의 MRE 가이드에서 유용한 기본 사항을 확인할 수 있습니다.

재현 가능한 예시 전략

Docker 이미지

Docker는 재현자의 시스템 상태를 문제와 격리시키므로 가장 독립적인 접근 방식입니다. uv의 공식 Docker 이미지로 시작하고 특정 버전을 고정합니다:

코드 · 명령
FROM ghcr.io/astral-sh/uv:0.5.24-debian-slim

아키텍처 전반에서 일관된 동작을 보장하기 위해 플랫폼을 명시적으로 지정합니다:

코드 · 명령
FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim

명령어가 포함된 예시:

코드 · 명령
FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim

RUN uv init /mre
WORKDIR /mre
RUN uv add pydantic
RUN uv sync
RUN uv run -v python -c "import pydantic"

또는 인라인 파일 내용을 포함하는 예시:

코드 · 명령
FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim

COPY <<EOF /mre/pyproject.toml
[project]
name = "example"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["pydantic"]
EOF

WORKDIR /mre
RUN uv lock

여러 파일의 경우 Git 레포지토리를 생성합니다. 확장된 빌드 출력을 보려면:

코드 · 명령
docker build . --progress plain --no-cache

스크립트

컨테이너화에 적합하지 않은 플랫폼별 버그의 경우 단계별 스크립트를 제공합니다:

코드 · 명령
uv init
uv add pydantic
uv sync
uv run -v python -c "import pydantic"

상세 출력(-v 플래그 사용)과 완전한 오류 메시지를 포함합니다. 특정 Python 설치, 패키지 관리자, 셸 버전과 같은 외부 의존성을 문서화합니다.

Git 레포지토리

스크립트 또는 Dockerfile을 동반한 Git 레포지토리를 공유합니다. 클로닝 및 체크아웃 지침을 포함합니다:

코드 · 명령
$ git clone https://github.com/<user>/<project>.git
$ cd <project>
$ git checkout <commit>
$ <commands to produce error>

GitHub UI 또는 gh CLI로 레포지토리를 생성합니다:

코드 · 명령
$ gh repo create uv-mre-1234 --clone

불필요한 파일과 설정을 제외하여 레포지토리 내용을 항상 최소화합니다.

원문(영어): https://docs.astral.sh/uv/reference/troubleshooting/reproducible-examples/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/reference/troubleshooting/reproducible-examples/