Pipenv 贡献开发指南：环境搭建、Owned vs Vendored 代码治理与测试体系全解析

Pipenv 贡献开发指南环境搭建、Owned vs Vendored 代码治理与测试体系全解析【免费下载链接】pipenvPython Development Workflow for Humans.项目地址: https://gitcode.com/gh_mirrors/pi/pipenvPipenv 是为人类设计的 Python 开发工作流工具它自动管理虚拟环境与依赖并通过Pipfile/Pipfile.lock实现确定性构建。本文以仓库根目录 CONTRIBUTING.md 与其完整正文 docs/dev/contributing.md 为核心骨架系统梳理向 Pipenv 提交代码、文档与 bug 报告的完整路径并深入讲解该项目极具特色的Owned项目自有vs Vendored供应商内置代码治理策略、基于 towncrier 的变更日志机制以及依赖本地 pypiserver 的测试体系。读完本文你将能独立完成从克隆仓库、搭建可编辑开发环境、编写 news fragment、运行全量测试到提交 Pull Request 的全过程并准确判断哪些代码可以自由重构、哪些代码必须交给 vendoring 工具链处理。贡献总览与协作基本规则Pipenv 的贡献指南按贡献类型分为若干章节但所有贡献者都需先遵守三条通用准则Be Cordial保持友善这是项目创始人 Kenneth Reitz 定下的黄金法则——保持友善否则请离开。所有贡献包括 bug 报告与特性请求都被欢迎前提是参与者彼此尊重。尽早获取反馈Get Early Feedback不必等到贡献完美无缺才提交。尽早提交未完成版本并不会降低被接受的概率反而能避免把大量工作投入到一个并不适合项目方向的贡献上。贡献适宜性Contribution Suitability项目维护者对贡献是否适合 Pipenv 拥有最终决定权。所有贡献都会被认真考虑但若与项目当前目标或需求不符可能会被拒绝只要遵循了本指南下一次贡献被接受的概率会更高。问题提问渠道GitHub Issue 追踪器只用于 bug 报告与特性请求不用于提问。使用类问题应发往 Stack Overflow 并打上pipenv标签以保证被及时且准确地解答。开发环境搭建可编辑安装与 pre-commit向 Pipenv 提交代码前需要先把仓库版本的 Pipenv 以**可编辑模式editable install**安装覆盖全局安装的其它版本以避免pipenv文件夹被隐式加入sys.path后产生冲突。Pipenv 借鉴了 pip 的做法使用pre-commit 钩子自动应用 lint 与代码格式化构建阶段也会校验这些 lint 规则一旦检测到未格式化的改动构建就会失败。因此搭建环境的完整流程为$ python -m pip install -e .[tests,dev] $ pipenv install --dev $ pipenv run python -m pip install -e .[tests,dev] # 配置在每次 commit 开始时执行 pre-commit 检查 $ pre-commit install # 如需针对全部项目文件校验 pre-commit 配置 $ pre-commit run --all-files --verbose其中[tests,dev]两组可选依赖在 pyproject.toml 中定义dev组包含black当前锁定black26.3.1、flake8、invoke、parver、sphinx、towncrier等开发工具tests组包含pytest、pytest-rerunfailures、pytest-timeout、pytest-xdist等测试工具。格式化的具体规则也定义在 pyproject.toml 中blackline-length 90并显式排除了pipenv/vendor、pipenv/patched、tests/pypi、tests/test_artifacts等目录——这正是下文Owned vs Vendored策略在工具链层面的落地ruffline-length 137启用了E/F/Wpyflakes/pycodestyle以及Iisort、UPpyupgrade、Bbugbear、PLpylint等几十个规则集同样排除了pipenv/patched/*与pipenv/vendor/*。也就是说lint 与格式化规则只约束自有代码供应商代码由工具链单独管理。这是理解 Pipenv 代码库组织方式的第一把钥匙。代码提交的标准流程文档给出的提交流程是一份清晰的检查清单在 GitHub 上 Fork 仓库按上文搭建开发环境运行测试确认本机全部通过若失败需自行排查无法定位时按 bug 报告规范提交 issue先编写能够演示该 bug 或新特性的测试并确认它们当前是失败的做出代码改动再次运行完整测试套件确认全部通过包括你新加的测试向主仓库的main分支发送 GitHub Pull Request。先写失败测试、再做实现的顺序是项目明确要求的测试先行既证明了 bug 的存在也防止了没有测试保护的改动混入主干。此外贡献在被合并前必须经过Code Review实现者应落实评审意见若强烈反对需冷静说明理由若评审意见最终仍被判定有效则要么落实、要么撤回贡献。Package Index测试用本地包源为加速测试依赖包索引用于 lock 与 install的测试都会使用 tests/pypi 目录下自带的供应商包通过本地服务器提供。为某个包新增 release 时优先使用.tar.gz或通用 wheel如py2.py3-none若两者均不可用则需为所有可用的架构与平台分别添加 wheel。Owned vs Vendored代码所有权治理策略这是 Pipenv 贡献指南中最具技术深度、也是编辑代码前必须理解的一节。pipenv/下的每个 Python 文件都严格处于两种状态之一知道文件处于哪种状态就决定了谁能编辑它、以及按什么规则编辑。不存在第三种状态。状态范围编辑规则Owned自有pipenv/下除pipenv/patched/与pipenv/vendor/之外的所有代码可自由重构适用项目规范、lintruff check pipenv/与测试覆盖要求没有上游需要同步Vendored供应商内置pipenv/patched/pip 的补丁副本与pipenv/vendor/第三方包禁止手改由项目的 vendoring 工具链从上游重新同步更新通过vendor:前缀的提交驱动工具链完成该策略的由来是项目用惨痛教训换来的最坏情况的中间态——多年前从上游库复制粘贴、从未再同步、在保持别人的代码不该动的错觉下与上游静默漂移——正是 Initiative B 清扫行动耗费五个工作单元才清理干净的问题。Pipenv 没有足够的人力去追踪已漂移的内联副本。因此如果一份上游代码值得保留在仓库内要么重新 vendor 到pipenv/vendor/让工具链跟踪它要么正式收养为自有代码让项目拥有它二选一。从仓库结构看vendoring 工具链的痕迹清晰可见tasks/vendoring/patches/patched 目录存放着作用于pipenv/patched/pip 补丁副本的补丁文件例如pipenv_import.patch、pip_specifier.patch、pip_tarfile_link_safety.patch等它们定义了 patched pip 相对上游的差异pyproject.toml 的 ruff/black 排除规则、以及 Makefile 中读取pipenv/patched/pip/__init__.py版本号来构建 wheel 的逻辑都印证了两棵树由工具管理、不手改的约定。例外刻意分叉Deliberate Forks自有代码树中保留上游函数的刻意分叉是允许的前提是分叉与上游行为有意不同且必须在 docstring 中携带Provenance来源声明注明所分叉的上游符号并写明刻意差异是什么。指南给出两个随 Initiative B Wave 1c 一起落地的范例读者可以在源码中直接验证pipenv/utils/requirements.py其中的redact_netloc与redact_auth_from_url是pip._internal.utils.misc.redact_netloc/redact_auth_from_url的刻意分叉差异在于保留环境变量占位符与标准 SSH 用户名而非改写成****差异在 docstring 中逐条注明pipenv/utils/requirementslib.pyunpack_url与get_http_url是对pip._internal.operations.prepare.unpack_url与get_http_url的原样收养docstring 点名了上游符号并标注了patched-pip 副本是否可直接调用这一待决问题。当你新增或大改一个分叉时请遵循同样的约定在 docstring 中写一段Provenance:段落点名上游符号与刻意差异。两年后的读者永远不该靠猜来判断某个函数是过时副本还是刻意分叉。支撑该策略的逐符号审计报告见 docs/dev/initiative-b-triage.md进一步了解项目现代化进程还可参考 docs/dev 下的多份 initiative 设计文档。News Fragments基于 towncrier 的变更日志机制Pipenv 使用 towncrier 管理变更日志。每个改变用户可见行为的 Pull Request 都必须附带一个 news fragment以确保改动被收录进下个版本的CHANGELOG.md。创建 News Fragmentfragment 文件放在 news/ 目录下命名为news/issue-number.type.rst其中type取值如下表与 pyproject.toml 中[tool.towncrier.type]的配置一一对应类型描述是否出现在 CHANGELOGfeature新特性或改进是behavior既有行为的变更是bugfix缺陷修复是vendor供应商内置库的更新是doc仅文档改进是removal弃用或移除是process开发/CI 流程变更是trivial拼写修复、重构或其他次要改动否不显示在 CHANGELOG例如为 issue #1234 的 bug 修复添加条目$ echo Fixed the frobnication logic when the widget is None. news/1234.bugfix.rst仓库 news/ 目录中的既有 fragment如6701.bugfix.rst、pip-26.2.vendor.rst正是这一约定的实例pip-*这类以开头的文件名与vendor类型对应由 vendoring 工具链驱动的供应商更新流程。Trivial Fragment 的特殊约定trivial类型用于不需要用户可见变更日志条目的改动内部重构、仅测试改动、注释拼写修复等$ echo . news/1234.trivial.rst注意CI 强制要求 trivial fragment 存在以此确认你已考虑过是否需要变更日志条目但它会被有意排除在生成的CHANGELOG.md之外——towncrier 会收集这些文件、删除它们并在输出中静默省略。fragment 内容无需多余文字单个.即可。本地预览变更日志在不改动任何文件的前提下预览下一个版本日志$ towncrier build --draft --version 9999.0.0该命令将草稿输出到 stdout。towncrier 的完整行为由 pyproject.toml 配置directory news/、filename CHANGELOG.md、template news/towncrier_template.rst各类型按Features Improvements、Bug Fixes、Vendored Libraries、Trivial Changes等分组渲染其中trivial明确设置了showcontent false。Bug 报告规范Bug 报告同样被视为重要贡献记录为 GitHub issue。提交时请注意避免重复 issue务必先用 issue 搜索功能检查历史。若搜索标题中的若干关键词就能找到原有 issue重复报告通常会被立即关闭附上完整 traceback关于异常的报告必须包含完整回溯。只有异常文本或部分回溯没有帮助缺失完整 traceback 的 issue 可能被直接关闭提供足够信息至少包括四要素如何复现理想情况下是维护者可立即运行的最小代码样本否则说明你的操作、发生频率、运行环境等预期结果运行示例代码后应该发生什么、怎样算成功实际结果具体如何失败——抛异常挂起安装的包不对实际与预期的差异是什么Pipenv 版本与安装方式不同版本行为不同、bug 也不同且部分发行版会在官方代码之上叠加补丁。若信息不全维护者会要求补充若始终不回应澄清请求issue 会在未修复的情况下被关闭。运行测试体系从 pytest 到本地 pypiserverPipenv 的测试采用pytest风格基础运行方式极其简单$ pytest但许多测试依赖运行在localhost:8080上的私有 pypi 服务器。文档提供了两种启动方式使用项目脚本 run-tests.shLinux/macOS或 run-tests.batWindows它们会在调用 pytest 之前先启动pypiserver手动启动后照常运行 pytest# Linux 或 MacOS pipenv run pypi-server run -v --host0.0.0.0 --port8080 --hash-algosha256 --disable-fallback ./tests/pypi/ ./tests/fixtures # Windows cmd /c start pipenv run pypi-server run -v --host0.0.0.0 --port8080 --hash-algosha256 --disable-fallback ./tests/pypi/ ./tests/fixturespypiserver 的包源是 tests/pypi 与 tests/fixtures 目录与上文Package Index一节的本地包策略互相印证run-tests.sh 中还能看到它使用临时缓存目录、用pipenv install --deploy --dev安装依赖、并执行git submodule sync git submodule update --init --recursive等完整步骤。运行子集标准 pytest 过滤器全量测试耗时较长可按标准 pytest 过滤器缩小范围指定目录或文件pytest tests/unit或pytest tests/unit/test_cmdparse.py关键字表达式pytest -k test_lock_editable_vcs_without_install指定 nodeidpytest tests/unit/test_cmdparse.py::test_parse指定标记pytest -m lock项目在 pyproject.toml 中注册了大量自定义 markerinstall、update、lock、sync、vcs、cli、needs_internet、flaky等pipenv run pytest --markers可列出全部同时通过norecursedirs显式跳过vendor、patched、news、tasks、docs、tests/test_artifacts、tests/pypi等目录。测试代码按 tests/unit单元测试与 tests/integration集成测试分层组织。三种进阶运行方式1. 测试脚本推荐在开 PR 前运行run-tests.sh 复刻了 GitHub CI 工作流的全部步骤因此文档明确建议在开 PR 之前运行它。可用环境变量覆盖默认行为$ PYTHONpython3.8 PIPENV_PYTHONpython3.9 run-tests.sh $ PYTHON/opt/python/python3.10/python3 run-tests.sh其中PYTHON覆盖 Python 二进制名默认python用于处理系统上不叫python的情况PIPENV_PYTHON覆盖 Pipenv 实际使用的解释器版本脚本默认值为3.8。2. 手动执行重复脚本步骤$ git clone https://github.com/pypa/pipenv.git $ cd pipenv $ git submodule sync git submodule update --init --recursive $ python -m pip install -e .[tests,dev] $ pipenv install --dev $ pipenv run python -m pip install -e .[tests,dev] $ pipenv run pytest [--any optional arguments to pytest]第二种方式的前提是系统上已装有 pipenv。文档特别建议在Linux 容器或 FreeBSD Jail、VM中运行测试以保证环境纯净、不破坏宿主机$ docker run --rm -v $(pwd):/usr/src -it python:3.7 bash # 容器内 # adduser --disabled-password debian # su debian cd /usr/src/ # bash run-tests.sh3. 使用 Makefile更细粒度的控制Makefile 自动化了脚本中的全部任务并允许对每个步骤做更精细的控制$ make ramdisk # 创建内存盘以保护 SSD 寿命 $ make ramdisk-virtualenv $ make test suite-m not cli # 运行除 cli 外的所有测试 $ make tests parallel suitetests/integration/test_cli.py::test_pipenv_check此外文档还给出 macOS 环境下的注意事项确保测试能访问 GitHub必要时启动ssh-agent并ssh-add、通过 brew 安装 coreutils 后把 GNU 工具加入PATH、并取消设置PIP_FIND_LINKS它当前会破坏test_uninstall.py。文档贡献文档改进同样随时欢迎。文档源文件位于 docs 目录采用 Markdown 编写由 Sphinx 生成整套文档。贡献文档时请注意遵循既有文档风格正文宽度软限制79 字符采用半正式、友好且平易近人的散文风格Python 代码示例使用单引号字符串hello而非hello。小结给 Pipenv 贡献者的行动清单结合本文一次完整的贡献之旅可以浓缩为**先读 docs/dev/contributing.md → Fork 并可编辑安装pip install -e .[tests,dev] pre-commit→ 判断改动落在 Owned 还是 Vendored 区域后者交给 vendoring 工具链不要手改→ 先写失败测试 → 实现改动新分叉记得写Provenance:docstring→ 为每个用户可见改动添加 news fragment → 用run-tests.sh跑通含本地 pypiserver 的全量测试 → 向main分支发 Pull Request。把握住Owned 自由重构、Vendored 绝不手改、刻意分叉必须声明来源这一核心治理原则你就能在这个代码库中安全、高效地提交高质量的贡献。【免费下载链接】pipenvPython Development Workflow for Humans.项目地址: https://gitcode.com/gh_mirrors/pi/pipenv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考