为 Pipenv 做贡献

如果您正在阅读本文，您可能对为 Pipenv 做出贡献感兴趣。非常感谢！开源项目的生死存亡取决于他们从其他人那里得到的支持，事实上，你甚至考虑为 Pipenv 项目做出贡献是非常慷慨的你。

本文档列出了为该项目做出贡献的指南和建议。如果您正在考虑做出贡献，请首先阅读本文档并了解如何为该项目做出贡献。如果您有任何问题，请随时联系主要维护者 Dan Ryan、Tzu-ping Chung 或 Nate Prewitt。

该指南根据您想做出的贡献类型分为几个部分，其中一个部分涵盖了所有贡献者的一般准则。

一般准则

亲切

亲切或随你。 —肯尼斯·赖茨

Pipenv 有一个非常重要的规则来管理所有形式的贡献，包括报告错误或请求功能。这条黄金法则是“ 亲切或随心所欲”。

欢迎所有贡献，只要所有参与的人都受到尊重。

获得早期反馈

如果你正在贡献，不要觉得有必要坐在你的贡献上，直到它被完美地打磨和完成。它可以帮助您参与的每个人尽早寻求反馈。提交早期的、未完成的贡献版本以供反馈绝不会影响您获得该贡献被接受的机会，并且可以避免您将大量工作投入到不适合该项目的贡献中。

供款适用性

我们的项目维护人员对贡献是否适合 Pipenv 拥有最终决定权。所有的贡献都会被仔细考虑，但有时，贡献会被拒绝，因为它们不适合项目的当前目标或需求。

如果您的贡献被拒绝，请不要绝望！只要您遵循这些准则，您将有更好的机会让您的下一个贡献被接受。

问题

GitHub 问题跟踪器用于 错误报告 和 功能请求 。请不要用它来询问有关如何使用 Pipenv 的问题。这些问题应该直接针对 Stack Overflow。在 Stack Overflow 上提问时，请确保您的问题带有 pipenv 标签，以确保及时准确地回答。

代码贡献

提交代码的步骤

贡献代码时，您需要遵循以下清单：

了解我们的开发理念。
在 GitHub 上分叉存储库。
设置您的开发设置
运行测试 (Testing) 以确认它们都通过您的系统。如果他们不这样做，您将需要调查他们失败的原因。如果您无法自行诊断，请按照本文档中的指南将其作为错误报告提出：错误报告。
编写测试来演示您的错误或功能。确保他们失败。
做出改变。
再次运行整个测试套件，确认所有测试都通过了 ，包括您刚刚添加的测试 。
向主存储库的 master 分支发送 GitHub 拉取请求。 GitHub Pull Requests 是该项目中预期的代码协作方法。

以下小节更详细地介绍了上述一些要点。

开发设置

要设置您的开发环境，请运行：

pip install -e .
pipenv install --dev

这将安装 Pipenv 的存储库版本，然后安装开发依赖项。完成后，您就可以开始开发了。

Pipenv 的存储库版本必须安装在其他全局版本上，以解决与隐式添加到 sys.path 的 pipenv 文件夹的冲突。有关更多详细信息，请参阅 pypa/pipenv#2557。

测试

测试以 pytest 风格编写，可以非常简单地运行：

pytest

这将运行所有 Pipenv 测试，这可能需要一段时间。要运行测试的子集，可以使用标准的 pytest 过滤器，例如：

提供目录或文件：pytest tests/unit 或 pytest tests/unit/test_cmdparse.py
提供关键字表达式：pytest -k test_lock_editable_vcs_without_install
提供一个节点 ID：pytest tests/unit/test_cmdparse.py::test_parse
提供测试标记：pytest -m lock

代码审查

在代码审查之前，不会合并贡献。除非您强烈反对，否则您应该实施任何代码审查反馈。如果您反对代码审查反馈，您应该清楚而冷静地说明您的情况。如果在这样做之后，判断反馈仍然适用，您必须应用反馈或撤回您的贡献。

包裹索引

为了加快测试速度，依赖包索引进行锁定和安装的测试使用包含 tests/pypi 目录中的供应商包的本地服务器。每个供应商包都应该有自己的文件夹，其中包含必要的版本。为软件包添加版本时，最容易使用 .tar.gz 或万向轮（例如：py2.py3-none）。如果 .tar.gz 或万向轮不可用，请为所有可用架构和平台添加轮子。

文档贡献

文档改进总是受欢迎的！文档文件位于代码库的 docs/ 目录中。它们用 reStructuredText 编写，并使用 Sphinx 生成全套文档。

在贡献文档时，请尽量遵循文档文件的风格。这意味着您的文本文件中的软限制为 79 个字符宽，并且采用半正式但友好且平易近人的散文风格。

呈现 Python 代码时，使用单引号字符串（'hello' 而不是 "hello"）。

错误报告

错误报告非常重要！它们被记录为 GitHub 问题。提交错误报告时请注意以下事项：

避免提出重复的问题。请使用GitHub问题搜索功能检查您的错误报告或功能请求是否在过去被提及。重复的错误报告和功能请求对于项目有限的资源来说是一个巨大的维护负担。如果您的报告清楚地表明您很难找到原件，那没关系，但是如果在您的问题标题中搜索选定的单词会找到重复项，那么该问题可能会非常突然地关闭。
在提交有关异常或回溯的错误报告时，请包括 完整的 回溯。部分回溯或仅异常文本没有帮助。不包含完整回溯的问题可能会在没有警告的情况下关闭。
确保提供适量的信息以供使用。这意味着您应该提供：
- 关于 如何重现问题的指南 。理想情况下，这应该是一个 small 代码示例，可以由维护人员立即运行。如果失败，请告诉我们您在做什么、发生的频率、您使用的环境等。彻底：它可以防止我们需要提出进一步的问题。
- 告诉我们 您预期会发生什么 。当我们运行您的示例代码时，我们期望发生什么？你的代码的“成功”是什么样的？
- 告诉我们 实际发生了什么 。说“它不起作用”或“它失败了”对您没有帮助。告诉我们如何失败：你有异常吗？挂？安装的软件包似乎不正确？实际结果与您的预期结果有何不同？
- 告诉我们 您使用的 Pipenv 版本，以及 您如何安装它。不同版本的 Pipenv 表现不同，有不同的错误，并且 Pipenv 的一些分销商在我们提供的代码之上发布补丁。
如果您不提供所有这些内容，我们将需要更长的时间来解决您的问题。如果我们要求您澄清这些，而您从未回应，我们将关闭您的问题而不修复它。

运行测试

运行测试的三种方式如下：

make test（使用 docker）
./run-tests.sh 或 run-tests.bat
使用pipenv：

$ git clone https://github.com/pypa/pipenv.git
$ cd pipenv
$ git submodule sync && git submodule update --init --recursive
$ pipenv install --dev
$ pipenv run pytest

对于最后两个，正确设置您的环境很重要，这可能需要一些工作，例如，在特定的 Mac 安装上，可能需要执行以下步骤：

# Make sure the tests can access github
if [ "$SSH_AGENT_PID" = "" ]
then
   eval `ssh-agent`
   ssh-add
fi

# Use unix like utilities, installed with brew,
# e.g. brew install coreutils
for d in /usr/local/opt/*/libexec/gnubin /usr/local/opt/python/libexec/bin
do
  [[../ ":$PATH:" != *":$d:"* ]] && PATH="$d:${PATH}"
done

export PATH

# PIP_FIND_LINKS currently breaks test_uninstall.py
unset PIP_FIND_LINKS

为 Pipenv 做贡献 — pipenv 文档