科学计算数据科学高性能计算【免费下载链接】scipySciPy library main repository项目地址https://gitcode.com/gh_mirrors/sc/scipy点击查看免费下载导读本文以 SciPy 官方贡献文档 hacking.rst 为核心系统梳理外部开发者向 SciPy 提交代码的完整路径从判断什么代码适合进入 SciPy到单元测试、基准测试、文档与代码风格四项硬性要求再到 API 组织方式、PR 评审流程与许可证合规性判断。阅读本文后你将掌握一套可立即落地的贡献流程知道新函数应该放在哪个子包、如何通过spin lint与 pre-commit 钩子通过风格检查、如何用spin test跑通测试以及如何在维护、评审与 issue 分拣中参与社区协作。贡献方式全景不止是写代码SciPy 社区欢迎的贡献远不止提交新代码这一种。根据官方文档以下工作都属于有效贡献贡献新的代码修复 Bug、改进文档以及其他维护性工作评审开放的 Pull RequestPR对 Issue 进行分拣triaging参与 scipy.org 网站建设在官方论坛回答问题和参与讨论。其中评审 PR和分拣 Issue是两类投入产出比很高的贡献前者能显著加快技术性 PR 的合入速度后者能帮助维护者在数百个开放 Issue 中快速定位优先级。文档特别指出如果你的专长在优化算法或特殊函数这类技术密集领域该方向的 PR 常常因缺少合适的评审者而长时间等待——你的专业评审意见正是社区最稀缺的资源。贡献新代码先判断代码是否适合进入 SciPy什么代码适合放进来文档给出的判断标准非常明确几乎所有合入 SciPy 的新代码都具备在多个科学领域都有潜在用途的特征并且落在现有子包subpackage的职责范围内。例如scipy.optimize、scipy.special、scipy.stats这类子包各自承担了明确的功能域。适合进入 SciPy跨领域通用、能匹配某个现有子包范围的代码不适合直接进入仅服务于单一应用的领域专属代码——这类代码更适合交给 scikit-learn、scikit-image、statsmodels 等聚焦特定领域的科学工具包它们比 SciPy 范围更窄、领域更专。原则上也可以新增子包但实践中极为罕见且必须经过更充分的社区讨论。合入前先讨论无论代码是否写完第一步都建议在 scipy-dev 论坛发起讨论。所有新特性与对现有代码的变更都要在这里讨论并达成决定。文档特别强调你的代码最终需要被别人评审所以尽早找到愿意评审你的人非常关键——理想情况下应该在代码尚未完成时就开始这一过程。关于新功能是否符合 SciPy 定位的更细致讨论可参考 adding_new.rst。合入前的四项硬性要求文档明确列出任何代码在被合入 SciPy 之前至少要具备良好的文档、单元测试、基准测试和正确的代码风格。这四项缺一不可。1. 单元测试覆盖所有新增代码原则上新代码应有覆盖其全部行为的单元测试。这能在你无法接触到的 Python 版本、硬件和操作系统组合上给出代码确实正确运行的信心。单元测试的编写规范详见 NumPy 的测试指南运行方式则见下文。撰写技巧还可以参考 writing_test_tips.rst。从仓库的实际开发工具看SciPy 统一使用spin命令驱动测试对应文档 devpy_test.rst。spin会先构建或增量更新SciPy 再运行测试常用用法包括# 运行全部测试 spin test # 只测某个子包例如 optimize spin test -s optimize # 运行某个测试文件 spin test -t scipy.optimize.tests.test_linprog # 运行测试类 spin test -t scipy.optimize.tests.test_linprog::TestLinprogRSCommon # 运行单个测试函数 spin test -t scipy.optimize.tests.test_linprog::test_unknown_solvers_and_optionsspin接口是自描述的spin --help与spin test --help可查看所有命令与用法示例。2. 基准测试用 airspeed velocity 监控性能回归单元测试验证功能正确性而基准测试衡量代码性能。并非所有现有 SciPy 代码都有基准测试但应该都有——随着项目膨胀监控执行时间以捕捉意外的性能回退越来越重要。写入与运行基准测试的方法见 benchmarking.rst。仓库中基准测试的实际组织方式可参考benchmarks/benchmarks/目录其中按子包划分了optimize.py、linalg.py、stats.py等基准文件。3. 文档docstring 是用户的说明书清晰完整的文档是用户能找到并理解代码的前提。文档要求包含函数与类的 docstring至少要有基础描述、全部参数与返回值的类型和含义以及 doctest 格式的使用示例这些 docstring 既可以在解释器中直接阅读也会被编译成 HTML 和 PDF 格式的参考指南关键功能区域还需要提供教程级文档和/或模块 docstring编写规范见 NumPy 的 docstring 指南本地预览渲染效果的方法见 rendering_documentation.rst。4. 代码风格PEP8 88 字符行宽SciPy 遵循标准 Python 风格规范 PEP8唯一例外是推荐最大行长为 88 字符而非 PEP8 的 79 字符。选择 88 字符是为了与 ruff、black 等主流工具默认值一致在更短文件、更少 lint 报错与保持合理行宽、支持并排查看文件之间取得平衡。仓库为统一风格提供了两层保障git pre-commit 钩子在 SciPy 仓库根目录执行一次安装之后每次提交都会自动做风格检查cp tools/pre-commit-hook.py .git/hooks/pre-commit手动运行 linterspin lint也可以在指定文件/目录上运行底层 lint 脚本python tools/linting/lint.py --files scipy/ndimage从源码 tools/linting/lint.py 可以看到风格检查的实际构成对 Python 文件调用ruff check --configlint.toml对 Cython 文件.pyx/.pxd/.pxi调用cython-lint --no-pycodestylelint.py还能通过git rev-list找到当前分支的分叉点只对本次改动涉及的*.py/*.pyx/*.pxd/*.pxi文件做检查。其配置位于 tools/linting/lint.toml要点包括line-length 88、target-version py312默认启用Epycodestyle 错误、W警告、FPyflakes、UPpyupgrade等规则并追加B006/B008禁止可变默认参数、B028warnings 需显式stacklevel、ICN001统一 import 惯例、RUF100清理无效 noqa等忽略E741模糊变量名允许下划线前缀的未使用变量各文件可按需豁免例如__init__.py豁免E402/F401等导入相关规则。IDE 侧也有辅助手段例如 Spyder 可开启实时代码风格分析并在保存时自动移除行尾空格。但要注意SciPy 的 lint 配置可能与 IDE 不完全一致最终以官方spin lint为准。更完整的风格细节参见 pep8.rst。代码放哪里理解 SciPy 的公共 API 结构新函数的位置取决于 SciPy 公共 APIapplication programming interface的组织方式。对大多数模块而言API 是两级深度即新函数应表现为scipy.subpackage.my_new_func形式。具体落地步骤将my_new_func放入scipy/subpackage/下某个现有或新建的模块文件在该文件中把函数名加入__all__列表该列表声明了文件内所有公共函数在scipy/subpackage/__init__.py中导入这些公共函数。以仓库中 scipy/optimize/init.py 为例文件顶部先给出模块级文档与autosummary索引随后导入minimize、minimize_scalar、OptimizeResult等公共 API。任何私有函数/类都应在名字前加下划线_例如_linprog.py、_minimize.py中的内部实现。完整的公共 API 定义与注意事项见 contributor 指南adding_new.rst 与 contributor_toc 中scipy-api一节。PR 流程与决策机制当代码就绪后通过 GitHub 发起 PR。文档建议为新特性发送 PR 时务必同时在 scipy-dev 论坛上提及——这会吸引感兴趣的人来协助评审。git 的具体使用方法可参考 gitwash 相关章节。代码评审的目的是确保代码正确、高效、满足上述要求。可能遇到的情况多数情况下评审推进较快也可能停滞如果你已回应全部反馈在过了一段时间比如几周后完全可以在论坛再次请求评审评审完成后PR 合入 SciPy 的main分支。决策机制的核心是共识consensus由所有选择参与论坛讨论的人共同决定包括开发者、其他用户和你自己。SciPy 是由科学 Python 社区创建、为科学 Python 社区服务的项目因此讨论中追求共识非常重要在极少数无法达成一致的情况下由对应模块的维护者拍板。PR 完整检查清单pr-checklist包含上述及更多要求。许可证考量BSD 兼容是硬门槛文档以 FAQ 形式回答了许可证相关问题我的代码基于网上找到的 Matlab/R 代码可以吗取决于来源许可证。SciPy 以 BSD 许可证分发因此兼容BSD、MIT、PSF 等 BSD 兼容许可证不可用GPL、Apache 许可证代码无明确许可证的代码要求引用的代码或仅限学术免费使用的代码若对某段代码做了直接翻译或复制同样不可纳入。不确定时应到 scipy-dev 论坛询问。为什么是 BSD 而不是 GPL与 Python 一样SciPy 采用允许专有再使用的宽松开源许可证。虽然这意味着公司可以在不回报的情况下使用和修改软件但社区的共识是更大的用户基础会带来更多的整体贡献而且企业往往即便不受强制也会公开自己的修改。仓库根目录的 LICENSE.txt 与 LICENSES_bundled.txt 可供进一步查阅。维护现有代码以失败测试先行修复 Bug前一节的讨论同样适用于已有代码的维护——修复 Bug、提升代码质量、补全文档、补充缺失的单元测试、添加性能基准、保持构建脚本最新等。Bug 修复的标准流程是先写一个能复现问题的单元测试——它本应通过但现在失败修复代码使测试转为通过提交 PR。与新增代码不同修复 Bug 通常不必先在论坛讨论——如果旧行为明显错误没人会反对修复。但对于行为变更可能需要补充警告或弃用deprecation提示这属于评审流程的一部分。文档还给出一个重要的社区约定见 hacking.rst 中的 note只改动代码风格、不涉及功能的 PR 不被鼓励。这类 PR 往往不值得污染 git 注解历史也会占用本可用在别处的评审时间但在功能性改动中顺带清理所触及代码的风格则是完全可以的。审阅 PR用这些问题评估他人代码评审开放 PR 是推动项目前进的宝贵方式也是熟悉代码库的最佳途径之一。文档建议评审者至少自问以下问题这次变更是否经过了充分讨论针对新特性与既有行为变更该特性在科学上是否站得住脚算法是否有文献支撑否则需要更仔细地审视正确性在所有条件下如空数组、nan/inf 等异常输入预期行为是否清晰代码是否满足前文所述的质量、测试与文档期望如果你还不为社区所知评审时不妨先做个自我介绍。更完整的本地评审操作见 reviewing_prs.rst。其他贡献方式分拣 Issue 与社区参与Issue 分拣SciPy 有数百个开放 Issue。关闭无效的、为有效的正确打标签最好在评论中附上初步思路能让维护工作按优先级推进并在处理某个函数/子包时轻松找到相关 Issue。详见 triage.rst。论坛参与在 scipy-user 与 scipy-dev 论坛的讨论本身就是贡献。每个带着问题或想法来信的人都期待回应认真作答能让项目运转得更好、社区氛围更友好。网站建设scipy.org 网站汇集了项目与社区的大量信息其源码在独立仓库中维护。开始行动下一步指引如果你准备贡献代码接下来建议按 contributor_toc.rst 给出的路线继续development_workflow.rst——配置开发环境、实现改进、提交第一个 PR 的完整流程包含合并前的 PR 检查清单devpy_test.rst——spin test构建并运行测试benchmarking.rst——用 airspeed velocity 编写与运行基准测试compiled_code.rst——用 Cython、C/C、Fortran 为性能敏感代码提速rendering_documentation.rst——本地渲染文档预览。记住贯穿全文的三条主线先讨论、再编码新功能先在论坛达成共识测试先行Bug 修复从失败的测试开始四件套齐全再提 PR单元测试、基准测试、文档、代码风格。遵循这套流程你的贡献就能以最小摩擦合入 SciPy。赞分享科学计算数据科学高性能计算【免费下载链接】scipySciPy library main repository项目地址https://gitcode.com/gh_mirrors/sc/scipy点击查看免费下载相关推荐Apache bRPC 贡献指南从 Issue 到 PR 的完整参与路径与代码规范Apache bRPC 贡献指南从 Issue 到 PR 的完整参与路径与代码规范 bRPC 是一个用 C 编写的工业级 RPC 框架常用于搜索、存储、后端RPC框架通信网络Mesop 贡献指南从 Issue 到代码合入的完整实践路径Mesop 贡献指南从 Issue 到代码合入的完整实践路径 Mesop 是一个面向 AI 应用开发的 Python Web 框架Rapidly buil前端后端Web框架react-beautiful-dnd 贡献指南全解析从提交 Issue 到合入 PR 的完整参与路径react beautiful dnd 贡献指南全解析从提交 Issue 到合入 PR 的完整参与路径 react beautiful dnd 简称 rbd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
