scikit-learn 贡献者指南从 Issue 提报到 PR 合入的完整开发流程【免费下载链接】scikit-learnscikit-learn: machine learning in Python项目地址: https://gitcode.com/gh_mirrors/sc/scikit-learn本文是 scikit-learn 开发者指南doc/developers/contributing.rst的深度导读系统讲解如何以符合项目规范的方式参与这个机器学习库的共建从了解贡献方式、提交高质量 Bug 报告到遵循开发工作流提交 PR、通过 PR 检查清单与自动化测试再到文档写作规范、性能基准与向后兼容deprecation策略。读完本文你将掌握一套可直接复用的、被 scikit-learn 维护者认可的贡献流程与工程习惯。为什么贡献 scikit-learn 是一份高门槛工作scikit-learn 自 2007 年诞生以来已演进为一个成熟而复杂的项目其贡献流程对质量的要求远高于普通开源项目。文档开篇即强调向 scikit-learn 提交 PR 需要人类判断力、上下文理解能力以及对项目结构与目标的熟悉程度它不适合由 AI 工具或随意使用的代码助手自动处理。维护者有权关闭由全自动工具生成的 Issue 或 PR并封禁相关账号。在动手之前你应当明确两点项目对新增算法和特性是选择性selective的因此最佳贡献方式是先解决已知问题known issues而不是凭空发明新功能。代码不是唯一的贡献方式审阅他人的 PR、在邮件列表或 Issue 中答疑、组织教程、维护网站、改进文档这些非代码贡献同样珍贵且社区一视同仁。关于贡献的具体分类详见 doc/developers/bug_triaging.rst关于项目治理与决策机制参考 doc/about.rst 与 doc/governance.rst所有沟通渠道必须遵守 CODE_OF_CONDUCT.md。自动化贡献政策Automated Contributions Policy这是近年来新增的重要章节值得所有使用 AI 辅助工具的开发者仔细阅读禁止提交完全由自动化工具生成的 Issue 或 PR维护者可自行判断关闭此类提交并封禁相关账户使用 AI 工具修改代码或文档后必须亲自审阅、理解并测试所有改动确保能随时向维护者解释不得提交未经审阅的 AI 生成代码不要在 Issue、PR 描述或评论中粘贴大段 AI 生成的文本这会让审查者难以评估你的贡献用于改善语法或为非英语母语者润色是可以的使用过 AI 工具必须在 PR 描述中如实声明违反该政策的 PR 将不做审查直接关闭。贡献的许可要求LicensingPR 以项目的BSD 3-Clause License见 COPYING接受。要打开 PR你必须有权利为贡献的每一部分授予该许可具体包括你拥有贡献的版权或雇主/客户已授权你以 BSD 3-Clause 许可贡献如果你已将该工作转让或独家许可给其他方包括那些以付费换取Work Product所有权的平台你通常无法再为该项目授予 BSD 3-Clause 许可——此时打开 PR 可能带来法律风险如违约、虚假陈述请在打开 PR之前确认授权维护者可能关闭那些明显违反项目流程、或把代码审查当作外部程序免费 QA 的 PR。提交 Bug 报告或功能请求项目使用 GitHub Issues 追踪所有 Bug 与功能请求。提交前请自查确认你的问题未被其他 Issues 或 PRs 处理若是算法/功能请求请确认其符合新算法收录标准文档中的 FAQ 链接若是 Bug 报告强烈建议遵循下述规范涉及 API 原则变更、依赖或支持版本变更的功能请求必须先提交SLEPscikit-learn Enhancement Proposal。如何写一份好的 Bug 报告理想的 Bug 报告包含一个短小可复现的代码片段详见 doc/developers/minimal_reproducer.rst任何人可以立即复现。超过约 50 行请链接到 Gist 或 GitHub 仓库。若无法提供可复现片段请具体说明涉及的 estimator/函数以及数据的形状。此外若抛出异常请提供完整 traceback包含操作系统类型与版本以及 Python、scikit-learn、numpy、scipy 版本可用以下命令一键获取python -c import sklearn; sklearn.show_versions()show_versions的实现位于 sklearn/utils/_show_versions.py它会打印系统信息、Python 依赖版本通过importlib.metadata.version获取缺失的依赖标记为None还会输出 OpenMP 并行支持状态与threadpoolctl线程池信息——这对排查数值/性能类问题尤其有用。代码片段与错误信息使用恰当的代码块格式明确说明该问题如何影响你作为用户简短段落帮助维护者把精力投入真正影响用户的 Issue告知维护者你是否愿意在问题被 triage 后打开 PR 修复。注意scikit-learn 的追踪器每天都会收到大量由 GitHub 账号自动生成的日报式报告这些账号主要为了刷贡献统计。项目希望评估维护精力是否对终端用户产生实际价值因此请勿为你并不真正关心的问题开 Issue。如果你想帮助整理 Issue请阅读 doc/developers/bug_triaging.rst。贡献代码与文档的整体流程首选方式是在 GitHub 上 fork 主仓库然后提交 Pull Request。整体步骤如下配置开发环境见 doc/developers/development_setup.rst找到要处理的问题见下文新贡献者部分遵循开发工作流对照 PR 检查清单逐项确认。为避免重复劳动强烈建议先搜索 Issue 追踪器与 PR 列表。最简单的方式是搜索带 help wanted 标签的 Issue——这类问题尚未被认领。如果你想认领在 Issue 下留言说明你的方案即可如果 2-3 周内别人已表示在做请让其完成否则可视为停滞stalled并接手。开发工作流Development Workflow同步与建分支# 1. 将 main 分支与 upstream/main 同步 git checkout main git fetch upstream git merge upstream/main # 2. 创建功能分支永远不要在 main 分支上直接开发 git checkout -b my_feature # 3. 完成编辑后提交 git add modified_files git commit git push -u origin my_feature注意若配置了 pre-commit 钩子git commit时可能自动格式化代码此时需要再次git addgit commit少数情况下需根据报错手动修复。创建 PR从 fork 创建 PR参考 GitHub 官方文档这会通知潜在审查者若 PR 数天内无人关注可在 Discord 开发频道发消息增加可见度不保证即时回复开发期间经常同步上游git fetch upstream与git merge upstream/main必要时手动解决冲突。Pull Request 检查清单PR Checklist文档将检查清单分为代码Code与文档Documentation两类分别对应打开前 / 打开时 / 打开后三个阶段。代码类 PR打开前PR 必须关联至少一个可认领的现有 Issue不要为标有 Needs triage 或其他 Needs... 标签、讨论未形成明确方案、报告者已表示要写 PR、或已有活跃关联 PR 的 Issue 开 PR没有相关 Issue 就先开一个讨论方案最重要的一点你必须理解自己要提交的代码不修改无关行保持 PR 聚焦于 Issue 声明的范围遵循编码指南见下文代码要有恰当注释与文档为 Bug 修复或新特性添加新测试。Bug 修复的测试在main分支上应失败、在 PR 代码上应通过CI 覆盖率测试会在新代码路径未被测试覆盖时失败涉及性能时附上基准脚本与 profiling 输出见 doc/developers/performance.rst所有测试本地通过见下文测试部分。新特性额外要求满足新算法收录标准新特性有维护开销PR 作者需至少初期参与维护在用户指南中配叙事性文档与小型代码片段必要时附文献引用尽量带 PDF 链接用户指南还应包含算法的时间/空间复杂度与可扩展性说明例如该算法可扩展到大量样本100000但不适合高维n_features应低于 100提供使用示例参考 examples/ 目录示例应展示新功能实际价值并尽量与库内其他方法对比。打开时给 PR 一个能概括贡献的有用标题合入后会成为 commit message——Fix #编号不是好标题在某些情况下 Fix 足够填写 .github/PULL_REQUEST_TEMPLATE.md 模板若 PR 解决某些 Issue/PR使用关键字建立关联如Fixes #1234可多个合入后 GitHub 会自动关闭它们。只是相关或部分解决时不要用关键字改用Towards #1234尚未完成的贡献应标记为draft PR草稿 PR可用于避免重复工作、请求对功能/API 的广泛审阅、寻找协作者描述中可包含任务列表。打开后添加 changelog 条目若 PR 可能影响用户格式见 doc/whats_new/upcoming_changes/README.md确保所有 CI 测试通过检查渲染后的文档见下文生成的文档耐心等待PR 合入前需要两位核心开发者批准。文档类 PR除纯拼写修正外同样要求关联可认领的 Issue遵循文档写作指南见下文确认可以在本地构建文档见下文构建文档标题以 DOC 开头同样填写模板、使用关键字关联 Issue、草稿 PR 规则一致。持续集成CI与 commit message 标记GitHub Actions负责在 Linux/Mac/Windows 上以不同依赖与设置测试 scikit-learn并构建 wheel 与源码发行包CircleCI负责构建供预览的文档。若最新 commit message 中出现以下标记CI 会采取相应动作Commit Message 标记CI 执行的动作[ci skip]完全跳过 CI[cd build]运行 CD构建 wheels 与源码发行包[scipy-dev]使用依赖numpy、scipy 等的开发版构建与测试[free-threaded]使用 CPython 3.14 free-threaded 构建与测试[pyodide]使用 Pyodide 构建与测试[float32]通过设置SKLEARN_RUN_FLOAT32_TESTS1运行 float32 测试[all random seeds]使用global_random_seedfixture 以全部随机种子运行测试[doc skip]不构建文档[doc quick]构建文档但不执行示例画廊example gallery的绘图[doc build]构建文档并执行示例画廊绘图非常耗时默认情况下文档会被构建但只执行 PR 直接修改的示例。解决环境/lock 文件冲突当上游更新导致build_tools/下的环境与 lock 文件冲突时可用以下脚本优先采用 upstream/main 的版本# 拉取最新 upstream/main git pull upstream main --no-rebase # 解决冲突——对特定文件保留 upstream/main 版本 git checkout --theirs build_tools/*/*.lock build_tools/*/*environment.yml \ build_tools/*/*lock.txt build_tools/*/*requirements.txt git add build_tools/*/*.lock build_tools/*/*environment.yml \ build_tools/*/*lock.txt build_tools/*/*requirements.txt git merge --continue合入后再重新生成 CI 用的环境与 lock 文件python build_tools/update_environments_and_lock_files.py该脚本位于 build_tools/update_environments_and_lock_files.py生成结果对应build_tools/github/下各*_environment.yml与*_conda.lock文件。新贡献者指南新贡献者建议先通读本指南重点是贡献方式与自动化贡献政策。然后通过以下途径建立对 scikit-learn 与开源的基础认知改进和调查 Issuedoc/developers/bug_triaging.rst确认问题可复现、补充最小复现代码doc/developers/minimal_reproducer.rst或调查问题根因以熟悉代码库审阅他人 PR理解贡献的质量要求改进文档加深对统计概念与 scikit-learn API 的理解。项目很少使用 good first issue 标签难以假设新贡献者水平且这类问题往往比预想复杂但仍值得留意有经验者可关注 Easy 标签的 Issue。推荐从小 PR起步并对照 PR 检查清单。关于哪些 Issue 已停滞、哪些 PR 可接手遵循 doc/developers/tips.rst 中的 etiquette。停滞的 PR 与未认领的 Issue判断 PR 是否停滞若 PR 带 stalled 或 help wanted 标签即为候选否则询问作者是否继续两周内无推进性活动即视为停滞并打上 help wanted。若 PR 收到评论后一个月无回复可安全假定停滞并将等待时间缩短为一天。Sprint 期间未合入的 PR 会标记 sprint由 sprint 负责人决定重新分配或宣告停滞。接手停滞 PR 时需在新旧 PR 上互相评论链接且新 PR 应从旧 PR 拉取创建。未认领的 Issue 一般带 help wanted 标签但并非全部。判断是否被认领检查关联 PR、查看对话中是否有人表示在做。新贡献者认领后应两周内提交 PR贡献者或核心开发者四周否则其他人可接手建议直接在 Issue 下留言告知社区你要开工。若 Issue 关联停滞 PR优先按停滞 PR 的流程处理。标有 Needs Triage 的 Issue 意味着问题尚未确认或完全理解社区需要先厘清问题、讨论范围、决定下一步。你可以参与讨论但在该标签移除、达成共识并明确解决方向之前不要开 PR。文档贡献Documentation文档贡献涵盖四类docstringAPI 文档描述对象功能与参数/属性/方法细节与代码一同位于 sklearn/ 中由 doc/api_reference.py 生成。要增删改或弃用列于 doc/modules/classes.rst 的公共 API从这里入手用户指南提供算法的详细说明位于 doc/ 与 doc/modules/示例完整代码示例位于 examples/其他 reStructuredText 文档位于 doc/。docstring 写作规范用 pytest 测试 docstring例如修改了RandomForestClassifier的 docstring 后pytest --doctest-modules sklearn/ensemble/_forest.py -k RandomForestClassifier节顺序为Parameters、Returns、See Also、Notes、Examples其他节参考 numpydoc 文档参数与属性格式示例n_clusters : int, default3 The number of clusters detected by the algorithm. some_param : {hello, goodbye}, bool or int, defaultTrue The parameter description goes here, which can be either a string literal (either hello or goodbye), a bool, or an int. The default value is True. array_parameter : {array-like, sparse matrix} of shape (n_samples, n_features) \ or (n_samples,) This parameter accepts data in either of the mentioned forms, with one of the mentioned shapes. The default value is np.ones(shape(n_samples,)). list_param : list of int typed_ndarray : ndarray of shape (n_samples,), dtypenp.int32 sample_weight : array-like of shape (n_samples,), defaultNone multioutput_array : ndarray of shape (n_samples, n_classes) or list of such arrays格式要点使用 Python 基础类型bool而非boolean形状用括号array-like of shape (n_samples,)多选字符串用花括号input: {log, squared, multinomial}array-like可为list而ndarray专指numpy.ndarray使用 frame-like 特性如列名时注明dataframe列表类型用of分隔list of int数组列表用array-like of shape (n_samples,) or list of such arrays指定 ndarray dtype 用dtypenp.int32任意精度用integral/floating默认值为None时以defaultNone结尾并说明None的含义。See Also 每行一个引用带冒号与说明See Also -------- SelectKBest : Select features based on the k highest scores. SelectFpr : Select features based on a false positive rate test.Notes 节可选给属性加 Note 需使用.. rubric:: Note指令Examples 节添加一两个可直接运行的代码片段含全部 import保持简洁。用户指南与 reStructuredText 文档写作规范在数学/算法细节与直觉之间保持平衡先给出一段简明直观的这个算法对数据做什么突出功能价值与推荐应用场景尽量给出复杂度如 $O(g(n))$没有复杂度再给经验法则配一张由示例生成的图增强直觉包含一两个简短代码示例数学公式放在文后并附参考文献编辑.rst文件时行宽尽量控制在 88 字符内链接和表格除外scikit-learn 的 rst 文件中单双反引号都会渲染为行内字面量常用于代码现在应使用单反引号用 dropdown 收纳低层级信息如 References、深入数学细节、特定用例的叙述语法为.. dropdown:: Dropdown title Dropdown content.注意不要在 dropdown 中使用Examples低层级节它应保持对所有用户可见且紧随主讨论之后dropdown 会破坏交叉引用必要时把引用与提及它的文本一起隐藏否则不要用 dropdown。参考文献写作规范有 arxiv 或 DOI 编号时使用 sphinx 指令:arxiv:或:doi:docstring 中的 References 节可参考sklearn.metrics.silhouette_score交叉引用语法节用标签 :ref:语法如.. _my-section:与:ref:my-section不要修改现有 sphinx 标签否则会破坏已有交叉引用与外链术语表:term:cross_validation函数:func:~sklearn.model_selection.cross_val_score若有.. currentmodule::指令可只写后续路径类:class:~sklearn.preprocessing.StandardScaler。构建文档提交 PR 前务必在本地构建文档以检查是否引入新的 sphinx 警告。先确保开发版安装正确doc/developers/development_setup.rst再安装额外依赖pip install sphinx sphinx-gallery numpydoc matplotlib Pillow pandas \ polars scikit-image packaging seaborn sphinx-prompt \ sphinxext-opengraph sphinx-copybutton plotly pooch \ pydata-sphinx-theme sphinx-design \ sphinx-remove-toctrees在doc目录下构建doc/Makefilecd doc # 仅生成网站不含示例画廊绝大多数情况 make # 含示例画廊会运行所有示例耗时较长 make html # 只运行文件名包含 plot_calibration 的示例 EXAMPLES_PATTERNplot_calibration make html文档生成在_build/html/stable目录可在浏览器打开_build/html/stable/index.html或启动本地服务器python -m http.server -d _build/html其他选项离线查看设置NO_MATHJAX1构建 PDF 手册运行make latexpdf。关于 Sphinx 版本不同版本行为略有差异为获得最佳效果应使用与 CircleCI 相同的 Sphinx 版本——可查看 build_tools/circle/doc_linux-64_conda.lock 中锁定的 sphinx 版本号。查看 CI 生成的文档PR 修改文档后GitHub Actions 会自动构建。在 PR 页面底部找到 Check the rendered docs here! 项并点击 details 即可查看。相关工作流配置见 build_tools/github/build_doc.sh。测试与测试覆盖率单元测试是 scikit-learn 开发过程的基石使用pytest。测试位于各模块的tests/子目录下函数命名规范。整套测试约需 10-20 分钟通常只需运行与改动相关的测试。例如修改了 sklearn/linear_model/_logistic.py 后# 确认 doctest 示例正确 pytest sklearn/linear_model/_logistic.py # 运行该文件专属测试 pytest sklearn/linear_model/tests/test_logistic.py # 测试整个 linear_model 模块 pytest sklearn/linear_model # 确认用户指南示例正确 pytest doc/modules/linear_model.rst # 运行全部 estimator 检查针对 LogisticRegression pytest sklearn/tests/test_common.py -k LogisticRegression其中sklearn/tests/test_common.py是 scikit-learn 的通用估算器测试核心sklearn/tests/test_common.py它通过sklearn.utils.estimator_checks中的check_estimator与parametrize_with_checks机制见 sklearn/utils/estimator_checks.py对所有估算器强制执行统一的 API 契约检查。pytest 的高效用法详见 doc/developers/tips.rst 中的 pytest 技巧部分。其他失败测试会被 CI 捕获无需在本地跑整套。还有两个实用约定matplotlib 相关测试使用测试套件内置的pyplotfixture它负责在 matplotlib 未安装时跳过测试并在测试结束后自动关闭创建的图形def test_requiring_mpl_fixture(pyplot): # you can now safely use matplotlib提高覆盖率的工作流安装coverage包后运行pytest --cov sklearn /path/to/tests查看未测试行号挑低垂果实补齐测试循环往复。性能监控asv 基准测试scikit-learn 使用 asv公共基准结果发布在 scikit-learn benchmarks 页面。完整使用 asv 需要conda或virtualenv。安装开发版 asv 并进入基准目录pip install githttps://github.com/airspeed-velocity/asv cd asv_benchmarks基准套件配置为针对本地 scikit-learn 克隆运行先确保其最新git fetch upstream基准按与 scikit-learn 相同的结构组织。比较upstream/main与当前分支上某个 estimator 的性能asv continuous -b LogisticRegression upstream/main HEAD常用变体# 使用 virtualenv 创建环境默认用 conda asv continuous -E virtualenv -b LogisticRegression upstream/main HEAD # 基准整个模块 asv continuous -b linear_model upstream/main HEAD # 运行全部基准可长达两小时 asv continuous upstream/main HEAD默认只报告变化至少 10% 的基准用-f控制该比率-b也接受正则表达式。只运行不做对比时用run命令# 基准当前 HEAD 的 linear_model asv run -b linear_model HEAD^! # 使用当前 Python 环境已安装的 scikit-learn适合 editable 安装避免重复建环境 asv run --pythonsame # 保存结果需指定 commit hash asv run --pythonsame --set-commit-hashcommit hash查看结果asv show列出所有已保存基准asv show commit hash查看特定运行的报告。为 PR 运行基准后请在 GitHub 上报告结果。基准套件支持在 asv_benchmarks/benchmarks/config.json 中配置额外选项例如{ profile: regular, n_jobs_vals: [1], save_estimators: false, base_commit: null, bench_predict: true, bench_transform: true }n_jobs_vals控制接受n_jobs参数的 estimator 要测试的取值列表-1表示全部核心空列表表示 1 到最大可用核心数profile可选regular/fast/large_scale各选项均可被环境变量如SKLBENCH_PROFILE、SKLBENCH_NJOBS覆盖。Issue 追踪器标签所有 Issue 和 PR 至少带以下标签之一标签含义Bug明确不该发生的事情正在发生——错误结果与意外报错Enhancement改进性能、可用性、一致性Documentation缺失、错误或不合格的文档与示例New Feature新功能请求及实现新功能的 PR另有四个帮助新贡献者的标签标签含义Good first issue首次贡献的理想选择有过经验者请转向 EasyEasy不需要太多经验即可着手Moderate可能需要一些机器学习或包的知识但对新人仍可上手Help wanted当前缺少贡献者或 PR 需要他人接手的标志注意并非所有需要贡献者的 Issue 都有此标签维护向后兼容弃用Deprecation策略任何公共类、函数、方法、属性或参数被重命名后旧版本仍支持两个发布周期并在被调用/传入/访问时发出弃用警告。警告消息必须同时给出弃用发生的版本与移除旧行为的版本若弃用发生在0.x-dev消息应写弃用于 0.x移除于 0.(x2)。例如弃用于 0.18-dev则应写 0.18 弃用、0.20 移除。消息还应简要说明变更原因并指向替代方案。弃用一个类或函数sklearn.utils.deprecated装饰器位于 sklearn/utils/deprecation.py源码显示它会根据被装饰对象类型分发类是_decorate_class包装__new__并保留签名见 PEP 362、property 是_decorate_property、其余是_decorate_fun统一发出FutureWarningfrom sklearn.utils import deprecated def zero_one_loss(y_true, y_pred, normalizeTrue): # actual implementation pass deprecated( Function zero_one was renamed to zero_one_loss in 0.13 and will be removed in 0.15. Default behavior is changed from normalizeFalse to normalizeTrue ) def zero_one(y_true, y_pred, normalizeFalse): return zero_one_loss(y_true, y_pred, normalize)还需在 doc/api_reference.py 中把zero_one从API_REFERENCE移到DEPRECATED_API_REFERENCE并把zero_one_loss加入API_REFERENCE。弃用一个属性或方法在 property 上使用deprecated装饰器。注意装饰器顺序deprecated应放在property之前源码_decorate_property正是依赖functools.wraps(prop.fget)包装 getter这样 docstring 才能正常渲染deprecated( Attribute labels_ was deprecated in 0.13 and will be removed in 0.15. Use classes_ instead ) property def labels_(self): return self.classes_弃用一个参数参数弃用需手动抛出FutureWarningimport warnings def example_function(n_clusters8, kdeprecated): if k ! deprecated: warnings.warn( k was renamed to n_clusters in 0.13 and will be removed in 0.15, FutureWarning, ) n_clusters k在类中则在fit里校验并告警import warnings class ExampleEstimator(BaseEstimator): def __init__(self, n_clusters8, kdeprecated): self.n_clusters n_clusters self.k k def fit(self, X, y): if self.k ! deprecated: warnings.warn( k was renamed to n_clusters in 0.13 and will be removed in 0.15., FutureWarning, ) self._n_clusters self.k else: self._n_clusters self.n_clusters此外还需在 docstring 中加入.. deprecated::指令例如.. deprecated:: 0.13 k was renamed to n_clusters in version 0.13 and will be removed in 0.15.并编写测试确保警告在相关场景触发、其他场景不触发其他测试用pytest.mark.filterwarnings捕获该警告示例中不得出现警告。修改参数的默认值需要修改参数默认值时将默认值替换为哨兵值如warn用户使用默认值时抛出FutureWarning。以下示例假设当前版本 0.20把n_clusters默认值从 50.20 旧默认改为 100.22 新默认import warnings def example_function(n_clusterswarn): if n_clusters warn: warnings.warn( The default value of n_clusters will change from 5 to 10 in 0.22., FutureWarning, ) n_clusters 5类中的写法是在fit中校验并告警。docstring 需用versionchanged指令更新.. versionchanged:: 0.22 The default value for n_clusters will change from 5 to 10 in version 0.22.测试要求与参数弃用相同确保警告按需触发其他测试捕获警告示例无警告。代码审查指南Code Review审阅他人 PR 是 scikit-learn 开发的重要一环对所有人都是极佳的学习机会。每个 PR 需两位核心开发者签署但任何人都可以通过反馈加速进程。注意客观改进与主观偏好nit的界限并不总是清晰审查的首要目标是降低项目风险——防止出现将来需要 Bug 修复、弃用或撤回的情况文档的拼写、语法与歧义问题应立即修正。审查应覆盖的关键方面从高层到细节我们是否真的需要这个功能用户是否会使用是否在 scikit-learn 范围内维护成本是否值得代码是否与 scikit-learn API 一致公共函数/类/参数命名是否直观所有公共函数/类及参数、返回类型、存储属性是否按规范命名并清晰文档化新功能是否在用户指南中描述并用示例说明每个公共函数/类是否被测试参数取值/类型/组合是否合理覆盖Bug 修复是否包含非回归测试non-regression test——该测试在修复前main分支应失败、修复后应通过从而保证后续改动不破坏预期行为CI 是否通过覆盖率报告是否覆盖每行代码代码是否易读、低冗余变量命名、注释是否恰当能否更高效地重写相关代码是否向后兼容必要时走弃用周期是否引入新的库依赖通常不会被接受文档渲染是否正确、绘图是否有指导性频繁使用的审查评论可参考 doc/developers/tips.rst 中保存的常用回复。沟通准则每个 PR无论好坏都是一种慷慨之举。以正面评论开场作者会感到被认可你后续的意见也更容易被听取尽量先谈大问题让作者知道被理解了抵制逐行挑刺或从小问题开场的冲动不要让完美成为优秀的敌人如果发现很多不属于代码审查范畴的小建议可以选择不提交、加 Nit 前缀让贡献者知道可以不处理、或在后续 PR 中跟进不急于求成花时间把评论写清楚并说明理由你是项目的门面状态不好时先休息保持离线。阅读现有代码库的技巧面对大型代码库以下技巧按重要程度排序能加速理解先熟悉 doc/developers/index.rst 提到的 API 概览理解fit、predict、transform等术语的用途读代码前先读 docstring尝试理解每个参数/属性并思考如果我来实现会怎么做最难的是判断哪些代码相关、哪些不相关scikit-learn 在fit方法开头做了大量输入检查真正的核心逻辑可能只有一小段。例如 sklearn/linear_model/_base.py 中LinearRegression.fit的关键不过是调用scipy.linalg.lstsq但它被埋在多层输入检查与参数处理之下由于大量使用继承一些方法在父类实现。所有 estimator 至少继承 sklearn/base.py 的BaseEstimator以及某个Mixin类如ClassifierMixin后者根据 estimator 性质分类器、回归器、转换器提供默认行为阅读某个函数的测试往往能快速理解其预期用途用git grep找到该函数的所有测试大多数模块的测试位于tests/目录你会经常看到out Parallel(...)(delayed(some_function)(param) for param in some_iterable)这类代码——这是用 Joblib 并行执行out是返回值的可迭代对象项目用 Cython 写高性能代码.pyx和.pxd文件涉及指针、手动内存分配等类 C 写法需要一定 C/C 经验详见 doc/developers/cython.rst善用工具IDE 的跳转/peek 定义功能、git blame查看文件演变、git grep查看模式出现位置配置git blame忽略迁移到 black/ruff 代码风格的那次提交git config blame.ignoreRevsFile .git-blame-ignore-revs对应的忽略文件是仓库根目录的 .git-blame-ignore-revs。常用资源索引开发环境搭建doc/developers/development_setup.rst最小复现代码指南doc/developers/minimal_reproducer.rst开发者提示pytest 技巧、常用审阅回复等doc/developers/tips.rst性能优化与 profiling 指南doc/developers/performance.rstCython 开发指南doc/developers/cython.rstIssue 分类triage指南doc/developers/bug_triaging.rst通用 estimator 检查实现sklearn/utils/estimator_checks.py弃用装饰器实现sklearn/utils/deprecation.py版本信息输出实现sklearn/utils/_show_versions.pyasv 基准配置asv_benchmarks/benchmarks/config.json掌握上述流程与规范后从认领一个 help wanted Issue 开始你的第一次贡献——记得先通读检查清单让代码、测试与文档三者齐头并进。【免费下载链接】scikit-learnscikit-learn: machine learning in Python项目地址: https://gitcode.com/gh_mirrors/sc/scikit-learn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考