为 Poetry 贡献代码

为 Poetry 贡献代码 #

首先，感谢您抽出时间贡献！

以下是关于在 GitHub 上为 Poetry 贡献代码的指南。这些主要是指南，而不是规则。请根据您的最佳判断，并随时在拉取请求中提出对本文档的更改建议。

如何贡献 #

报告错误 #

本节将指导您提交 Poetry 的错误报告。遵循这些指南有助于维护人员和社区了解您的报告，重现行为并找到相关的报告。

在提交错误报告之前 #

• 查看 常见问题解答，了解常见问题和问题的列表。
• 查看 博客，了解最近发布的版本说明，包括升级步骤和已知问题。
• 检查您的问题是否已存在于 问题跟踪器 中。
• 确保您的问题确实是错误，而不是更适合 讨论 或 Discord 的支持请求或问题。

如何提交错误报告？ #

有关 Poetry 和 poetry-core 的错误应提交到主 问题跟踪器，使用正确的 问题模板。

解释问题并使其易于他人搜索和理解

• 使用清晰且描述性的标题来标识问题。
• 尽可能详细地描述重现问题的准确步骤。
• 描述您在执行完这些步骤后观察到的行为，并指出这如何是一个错误。
• 解释您期望看到哪些行为，以及原因。
• 如果问题涉及引发意外错误，请在调试模式下（使用-vvv标志）执行有问题的命令。

提供详细的步骤来重现您的问题

• 在 Gist、pastebin 或示例存储库中提供您的 pyproject.toml 文件，在删除潜在的私人信息（如私人包存储库或名称）后。
• 提供具体的示例来演示重现问题的步骤。这可能是一个示例存储库、在容器中运行的一系列步骤，或者只是针对非常简单情况的 pyproject.toml。
• 您无法可靠地重现问题吗？如果是，请提供有关问题发生的频率以及通常发生在哪些条件下的详细信息。

通过回答以下问题提供更多上下文

• 问题是最近开始发生的（例如，在更新到新版本的 Poetry 之后）还是一直存在问题？
• 如果问题是最近开始发生的，您可以在旧版本的 Poetry 中重现问题吗？问题没有发生的最新的版本是什么？
• 您的环境是否存在任何奇特或不寻常之处？这可能包括使用特殊的容器映像、Apple Silicon 等更新的 CPU 架构，或拦截或修改网络流量的企业代理。

包含有关您的配置和环境的详细信息

• 您使用的是哪个版本的 Poetry？您可以通过运行poetry --version来获取确切的版本。
• 用于运行 Poetry 的 Python 版本是什么？执行poetry debug info以获取此信息。
• 您使用的操作系统的名称和版本是什么？例如，Ubuntu 22.04 或 macOS 12.6。

为了让其他人有最大的机会理解和重现您的问题，请务必在您的重现步骤上投入额外的精力。您既可以排除您这边本地配置问题，也可以确保其他人可以在原始容器（或 VM）中干净地重现您的问题，并在您的问题报告中提供您在该容器/VM 中执行的步骤。

建议改进 #

本节将指导您提交 Poetry 的改进建议，包括全新的功能以及对现有功能的改进。遵循这些指南有助于维护人员和社区了解您的建议并找到相关的建议。

在提交改进建议之前 #

• 查看 常见问题解答，了解常见问题和问题的列表。
• 检查您的问题是否已存在于 问题跟踪器 中。

如何提交改进建议？ #

有关 Poetry 和 poetry-core 的改进建议应提交到主 问题跟踪器，使用正确的 问题模板。

• 使用清晰且描述性的标题来标识建议。
• 提供对所提议改进的详细描述，并在可能的情况下提供具体的步骤或示例。
• 描述当前的行为，并解释您希望看到哪些行为，以及原因。

文档贡献 #

参与项目最简单的方式之一就是改进文档。Poetry 不断发展，这意味着有时我们的文档会有缺漏。您可以通过添加缺失的部分、编辑现有内容使其更易于访问或创建新的内容（如教程、常见问题解答等）来提供帮助。

与文档相关的 Issue 通常会标记为 area/docs 标签，这也会触发对该网站渲染的更改的预览。

代码贡献 #

选择 Issue #

如果您想处理某个 Issue，请随时在 Issue 上评论并标记 @python-poetry/triage。我们很乐意在 Issue 上讨论解决方案。如果您需要帮助浏览代码库、寻找要处理的内容或想要获得设计或更改的反馈，请加入我们的 Discord 服务器 或开始 讨论。

本地开发 #

Poetry 使用 Poetry 开发。请参考 文档 在本地环境中安装 Poetry。

您应该首先 fork Poetry 仓库，然后在本地克隆它，以便您可以针对项目进行 pull request。如果您不熟悉 Git 和基于 pull request 的开发，GitHub 提供了一个 指南，您会发现它很有用。

接下来，您应该安装 Poetry 的依赖项，并运行测试套件以确保一切按预期工作。

poetry install
poetry run pytest

当您为 Poetry 贡献代码时，将运行自动化工具以确保您的代码适合合并。除了 pytest 之外，您还需要确保您的代码使用 mypy 正确地进行类型检查。

poetry run mypy

最后，将在您的代码上运行大量 linting 工具，以尝试确保一致的代码风格并找出常见的错误。 pre-commit 工具用于安装和运行这些工具，并且需要一次性设置。

poetry run pre-commit install

pre-commit 现在将在您每次提交时运行并检查您的代码。默认情况下，它只会在更改的文件上运行，但您可以手动在所有文件上运行它（如果您更改了 pre-commit 配置，这可能很有用）。

poetry run pre-commit run --all-files

Pull Request #

• 完整填写 pull request 内容，并尽可能准确地描述您的更改。pull request 内容应保持最新，因为它通常会构成最终合并提交和更改日志条目的基础。
• 确保您的 pull request 包含涵盖更改或添加的代码的测试。测试通常是代码被认为可合并的必要条件，没有通过测试的代码将不会被合并。
• 确保您的 pull request 通过 mypy 和 pre-commit 检查。请记住，您可以本地运行这些工具，而不是依赖远程 CI。
• 如果您的更改需要文档更改，pull request 也必须更新文档。确保查看 CI 生成的文档预览，以查看是否有任何渲染问题。

所有 pull request，除非另有说明，都需要先被接受到 main 分支。维护者通常会决定是否需要对其他分支进行任何回退，并在需要时进行回退。

Issue 分流 #

如果您正在帮助分流报告的 Issue，本节提供了一些有用的信息来帮助您进行贡献。

分流步骤 #

1. 确定 Issue 与 Poetry 的哪些区域和版本相关，并设置相应的标签（例如 version/x.x.x、area/docs、area/venv），并删除 status/triage 标签。
2. 如果请求的信息（如调试日志、pyproject.toml 等）未提供且相关，请从作者处请求。
   1. 在等待作者回复时设置 status/waiting-on-response 标签。
3. 尝试使用报告的 Poetry 版本重现 Issue，或从作者处请求进一步说明。
4. 确保 Issue 尚未解决。尝试在最新的稳定版本、最新的预发布版本（如果有）和开发分支上重现它。
5. 如果无法重现 Issue，
   1. 从 Issue 的作者处请求更多重现步骤和说明，
   2. 设置 status/needs-reproduction 标签，
   3. 如果无法重现，请关闭 Issue。
6. 如果可以重现 Issue，
   1. 在 Issue 上评论确认，
   2. 设置 status/confirmed 标签，
   3. 如果可能，确定 Issue 的根本原因，
   4. 如果您有兴趣，请尝试通过 pull request 来修复它。

多个版本 #

在尝试重现 Issue 时，您通常希望同时使用多个版本的 Poetry。 pipx 使这变得很容易。

pipx install --suffix @1.2.1 'poetry==1.2.1'
pipx install --suffix @1.3.0rc1 'poetry==1.3.0rc1'
pipx install --suffix @main 'poetry @ git+https://github.com/python-poetry/poetry'
pipx install --suffix @local '/path/to/local/clone/of/poetry'

# now you can use any of the chosen versions of Poetry with their configured suffix, e.g.
poetry@main --version

pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head