Skip to content

Reproducible examples再現可能な例

Why reproducible examples are important再現可能な例が重要な理由

A minimal reproducible example (MRE) is essential for fixing bugs. Without an example that can be used to reproduce the problem, a maintainer cannot debug it or test if it is fixed. If the example is not minimal, i.e., if it includes lots of content which is not related to the issue, it can take a maintainer much longer to identify the root cause of the problem.最小限の再現可能な例（MRE）は、バグ修正に不可欠です。問題を再現するために使用できる例がなければ、メンテナはそれをデバッグしたり、修正されたかどうかをテストしたりすることができません。例が最小限でない場合、つまり、問題に関連しない多くのコンテンツが含まれている場合、メンテナが問題の根本原因を特定するのに時間がかかることがあります。

How to write a reproducible example再現可能な例の書き方

When writing a reproducible example, the goal is to provide all the context necessary for someone else to reproduce your example. This includes:再現可能な例を書く際の目標は、他の誰かがあなたの例を再現するために必要なすべてのコンテキストを提供することです。これには次のものが含まれます：

  • The platform you're using (e.g., the operating system and architecture)使用しているプラットフォーム（例：オペレーティングシステムとアーキテクチャ）
  • Any relevant system state (e.g., explicitly set environment variables)関連するシステム状態（例：明示的に設定された環境変数）
  • The version of uvuvのバージョン
  • The version of other relevant tools他の関連ツールのバージョン
  • The relevant files (the uv.lock, pyproject.toml, etc.)関連するファイル（uv.lock、pyproject.tomlなど）
  • The commands to run実行するコマンド

To ensure your reproduction is minimal, remove as many dependencies, settings, and files as possible. Be sure to test your reproduction before sharing it. We recommend including verbose logs from your reproduction; they may differ on your machine in a critical way. Using a Gist can be helpful for very long logs.再現性を最小限に保つために、できるだけ多くの依存関係、設定、およびファイルを削除してください。共有する前に、再現性をテストすることを忘れないでください。再現性からの詳細なログを含めることをお勧めします。これらは、あなたのマシンで重要な方法で異なる場合があります。非常に長いログには、Gistを使用することが役立ちます。

Below, we'll cover several specific strategies for creating and sharing reproducible examples.以下では、再現可能な例を作成し共有するためのいくつかの特定の戦略について説明します。

Tipヒント

There's a great guide to the basics of creating MREs on Stack Overflow.MREを作成する基本についての素晴らしいガイドがあります。 Stack Overflowで。

Strategies for reproducible examples再現可能な例のための戦略

Docker imageDockerイメージ

Writing a Docker image is often the best way to share a reproducible example because it is entirely self-contained. This means that the state from the reproducer's system does not affect the problem.Dockerイメージを書くことは、再現可能な例を共有するための最良の方法であることが多いです。なぜなら、それは完全に自己完結型だからです。これは、再現者のシステムの状態が問題に影響を与えないことを意味します。

Note注意

Using a Docker image is only feasible if the issue is reproducible on Linux. When using macOS, it's prudent to ensure your image is not reproducible on Linux but some bugs are specific to the operating system. While using Docker to run Windows containers is feasible, it's not commonplace. These sorts of bugs are expected to be reported as a script instead.Dockerイメージを使用することは、問題がLinuxで再現可能な場合にのみ実行可能です。macOSを使用する場合、Linuxで再現可能でないことを確認することが賢明ですが、一部のバグはオペレーティングシステムに特有です。Windowsコンテナを実行するためにDockerを使用することは可能ですが、一般的ではありません。この種のバグはスクリプトとして報告されることが期待されます。

When writing a Docker MRE with uv, it's best to start with one of uv's Docker images. When doing so, be sure to pin to a specific version of uv.uvを使用してDocker MREを書くときは、uvのDockerイメージのいずれかから始めるのが最良です。その際、特定のバージョンのuvに固定することを忘れないでください。

FROM ghcr.io/astral-sh/uv:0.5.24-debian-slim

While Docker images are isolated from the system, the build will use your system's architecture by default. When sharing a reproduction, you can explicitly set the platform to ensure a reproducer gets the expected behavior. uv publishes images for linux/amd64 (e.g., Intel or AMD) and linux/arm64 (e.g., Apple M Series or ARM)Dockerイメージはシステムから隔離されていますが、ビルドはデフォルトでシステムのアーキテクチャを使用します。再現を共有する際には、プラットフォームを明示的に設定して、再現者が期待される動作を得られるようにできます。uvはlinux/amd64（例：IntelまたはAMD）およびlinux/arm64（例：Apple MシリーズまたはARM）のイメージを公開します。

FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim

Docker images are best for reproducing issues that can be constructed with commands, e.g.:Dockerイメージは、コマンドで構築できる問題を再現するのに最適です。例えば：

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"

However, you can also write files into the image inline:ただし、インラインでイメージにファイルを書くこともできます：

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

If you need to write many files, it's better to create and publish a Git repository. You can combine these approaches and include a Dockerfile in the repository.多くのファイルを書く必要がある場合は、Gitリポジトリを作成して公開する方が良いです。これらのアプローチを組み合わせて、リポジトリにDockerfileを含めることができます。

When sharing a Docker reproduction, it's helpful to include the build logs. You can see more output from the build steps by disabling caching and the fancy output:Dockerの再現を共有する際には、ビルドログを含めると役立ちます。キャッシュとファンシー出力を無効にすることで、ビルドステップからの出力をさらに見ることができます：

docker build . --progress plain --no-cache

Scriptスクリプト

When reporting platform-specific bugs that cannot be reproduced in a container, it's best practice to include a script showing the commands that can be used to reproduce the bug, e.g.:再現できないプラットフォーム固有のバグを報告する際には、バグを再現するために使用できるコマンドを示すスクリプトを含めることがベストプラクティスです。例えば：

uv init
uv add pydantic
uv sync
uv run -v python -c "import pydantic"

If your reproduction requires many files, use a Git repository to share them.再現に多くのファイルが必要な場合は、それらを共有するためにGitリポジトリを使用してください。

In addition to the script, include verbose logs (i.e., with the -v flag) of the failure and the complete error message.スクリプトに加えて、失敗の詳細ログ（すなわち、-vフラグを使用したもの）と完全なエラーメッセージを含めてください。

Whenever a script relies on external state, be sure to share that information. For example, if you wrote the script on Windows, and it uses a Python version that you installed with choco and runs on PowerShell 6.2, please include that in the report.スクリプトが外部の状態に依存している場合は、その情報を共有することを忘れないでください。例えば、スクリプトをWindowsで作成し、chocoでインストールしたPythonのバージョンを使用し、PowerShell 6.2で実行する場合は、その情報を報告に含めてください。

Git repositoryGitリポジトリ

When sharing a Git repository reproduction, include a script that reproduces the problem or, even better, a Dockerfile. The first step of the script should be to clone the repository and checkout a specific commit:Gitリポジトリの再現を共有する際は、問題を再現するためのスクリプトを含めるか、さらに良いのはDockerfileを含めてください。スクリプトの最初のステップは、リポジトリをクローンし、特定のコミットをチェックアウトすることです：

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

You can quickly create a new repository in the GitHub UI or with the gh CLI:GitHub UIまたはgh CLIを使用して、新しいリポジトリをすぐに作成できます：

$ gh repo create uv-mre-1234 --clone

When using a Git repository for a reproduction, please remember to minimize the contents by excluding files or settings that are not required to reproduce your problem.Gitリポジトリを再現に使用する際は、問題を再現するために必要ないファイルや設定を除外して、内容を最小限にすることを忘れないでください。