贡献指南

• 简介

• 撰写有用的错误报告

• 安装最新版本

• 设置本地开发环境

  • Fork 仓库

  • 创建 Python 环境

  • 从源码安装

  • 使用 precommit 进行代码检查

  • 使用 pytest 进行单元测试

• Pull Requests (PRs)

  • 创建 PR 的礼仪

  • 发布 PR 的检查清单

• 文档

  • 在 Pull Requests 上预览更改

  • 在本地构建文档

• Jupyter Notebook 风格指南

  • 通用 Jupyter 指南

  • 链接 / 交叉引用

  • Notebook 代码检查和格式化

• 维护者指南

  • Issue 分流

  • PR 分流

  • 版本控制

  • 最低支持的依赖项

  • 发布版本

  • 从 PR 标签生成发行说明

简介

感谢您为 SHAP 做出贡献。SHAP 是一项开源集体努力，欢迎各种形式的贡献！

您可以通过以下方式贡献：

• 在 GitHub issue 跟踪器上提交错误报告和功能请求，

• 通过 Pull Requests 贡献修复和改进，或者

• 在 Discussions 论坛中讨论想法和问题。

如果您正在寻找一个好的入门点，请查找带有 good first issue 标签的 issues。

撰写有用的错误报告

在 issue 跟踪器上提交错误报告时，包含一个良好的最小可复现示例 (MRE) 对维护者非常有帮助。

一个 MRE 应该是

• 最小化：使用尽可能少的代码，但仍然能重现相同的问题。

• 自包含：包含重现问题所需的一切，包括导入和输入数据。

• 可复现：测试您即将提供的代码，以确保它可以重现问题。

有关更多信息，请参阅 如何编写最小化的错误报告。

安装最新版本

要获取 SHAP 的最新版本，您可以直接从 master 分支 pip 安装库

pip install git+https://github.com/shap/shap.git@master

这对于测试特定 issue 或错误是否已在最新版本中修复非常有用。

或者，如果您正在考虑更改代码，您可以克隆仓库并安装您的本地副本，如下所述。

设置本地开发环境

Fork 仓库

点击 此链接 在 GitHub 上将仓库 Fork 到您的用户区域。

使用您的项目主页上绿色 <> Code 按钮提供的 URL，将仓库克隆到您的本地环境。

创建 Python 环境

为项目创建一个新的隔离环境，例如使用 conda

conda create -n shap python=3.11
conda activate shap

从源码安装

要从源码构建，您需要一个编译器来构建 C 扩展。

• 在 Linux 上，您可以使用以下命令安装 gcc：

  sudo apt install build-essential
  

• 或者在 Windows 上，获取编译器的一种方法是 安装 mingw64。

使用 --editable 标志 pip 安装项目，这可确保您对源代码所做的任何更改都会立即反映在您的环境中。

pip install --editable '.[test,plots,docs]'

各种 pip extras 在 pyproject.toml 中定义

• test-core：运行 pytest 的最小依赖项集。

• test：用于完整测试套件的更广泛的第三方软件包集，例如 tensorflow、pytest、xgboost。

• plots：包括 matplotlib。

• docs：使用 Sphinx 构建文档的依赖项。

注意：从源码安装时，SHAP 将尝试构建 C 扩展和 CUDA 扩展。如果 CUDA 不可用，SHAP 将在不使用 CUDA 支持的情况下重试构建。

因此，如果您没有 CUDA 可用，则从源码构建时看到诸如 WARNING: Could not compile cuda extensions 之类的警告是很正常的。

使用 precommit 进行代码检查

我们使用 pre-commit hooks 来运行代码检查。使用以下命令在您的本地环境中启用 pre-commit：

pip install pre-commit
pre-commit install

要对所有文件运行检查，请使用：

pre-commit install
pre-commit run --all-files

Ruff 用作 linter，并且已启用为 pre-commit hook。您也可以使用以下命令在本地运行 ruff：

pip install ruff
ruff check .

使用 pytest 进行单元测试

单元测试套件可以在本地使用以下命令运行：

pytest

有关 matplotlib 测试的信息，请参阅 tests/plots/__init__.py。

Pull Requests (PRs)

创建 PR 的礼仪

在开始 PR 之前，请通过打开 Issue 提出建议，并检查是否有重复项。对于修复错别字等琐碎的 PR，这不是必需的。

保持范围小。这使得 PR 更容易审查。将功能代码更改（例如错误修复）与重构更改（例如样式改进）分开。PR 应该包含其中一个，但不能同时包含两者。

尽早打开 Draft PR，不要等到功能准备就绪。在具有描述性名称（例如 fix/lightgbm-warnings 或 doc/contributing）的功能分支上工作。

使用描述性标题，例如：

• FIX: 更新 参数 以删除 TreeExplainer 中的 DeprecationWarning

• ENH: 添加 对 python 3.11 的支持

• DOCS: 修复 ExactExplainer 文档字符串的 格式

发布 PR 的检查清单

在将您的 PR 标记为“准备好审查”（通过删除 Draft 状态）之前，请确保

• 您的功能分支与 master 分支保持同步，

• 所有 pre-commit hooks 通过，并且

• 已添加单元测试（如果您的 PR 添加了任何新功能或修复了错误）。

文档

文档托管在 shap.readthedocs.io。如果您修改了文档字符串或 notebooks，请同时检查更改是否在生成的 HTML 文件中正确呈现。

在 Pull Requests 上预览更改

文档会在每个 Pull Request 上自动构建，以方便预览您的更改将如何呈现。要查看预览：

1. 查找“All checks have passed”，然后单击“Show all checks”。

2. 浏览到名为“docs/readthedocs.org”的检查。

3. 单击 Details 超链接以打开文档的预览。

PR 预览通常托管在以下形式的 URL 上，替换 <pr-number>

https://shap--<pr-number>.org.readthedocs.build/en/<pr-number>

在本地构建文档

要在本地构建文档：

1. 导航到 docs 目录。

2. 运行 make html。

3. 在浏览器中打开 “_build/html/index.html” 以检查文档。

请注意，nbsphinx 当前需要独立的程序 pandoc。如果您收到错误 “Pandoc wasn’t found”，请按照 nbsphinx 安装指南 中的说明安装 pandoc。

文档依赖项固定在 docs/requirements-docs.txt 中。这些可以使用该文件顶部指定的 uv 命令更新，可以选择使用 --upgrade 标志。

Jupyter Notebook 风格指南

如果您正在为文档中的 Jupyter notebooks 贡献更改，请遵守以下风格指南。

通用 Jupyter 指南

在提交您的 notebook(s) 之前：

• 确保您“重启内核并运行所有单元格...”，确保单元格按顺序执行，notebook 是可重现的，并且没有任何隐藏状态。

• 确保 notebook 不会因您的更改而在 Sphinx 构建日志中引发语法警告。

链接 / 交叉引用

如果链接可以为读者提供有关手头主题的更多背景/上下文，建议您尽可能在 notebooks 中包含链接。

以下是如何在 notebook 的 Markdown 单元格中完成此操作的示例：

# Force Plot Colors

The [scatter][scatter_doclink] plot create Python matplotlib plots that can be customized at will.

[scatter_doclink]: ../../../generated/shap.plots.scatter.rst#shap.plots.scatter

其中指定的链接是 Sphinx 生成的 rst 文件的相对路径。优先使用相对链接而不是绝对路径。

Notebook 代码检查和格式化

我们使用 ruff 对我们的 notebooks 执行代码检查和自动格式化。假设您已按照 上面 的描述设置了 pre-commit，这些检查将在您提交任何更改时自动运行。

要手动运行代码质量检查，您可以执行例如：

pre-commit run --files notebook1.ipynb notebook2.ipynb

将 notebook1.ipynb 和 notebook2.ipynb 替换为您修改的任何 notebook(s)。

维护者指南

Issue 分流

错误报告和功能请求在 github issue 跟踪器上进行管理。我们使用自动化来帮助优先排序和组织 issues。

good first issue 标签应分配给任何可能适合新贡献者的 issue。

如果需要作者提供更多信息，例如可重现的示例，则应分配 awaiting feedback 标签。

stale bot 将标记长时间没有活动的 issues 和 PRs，并带有 stale 标签，并评论以征求我们社区的反馈。如果仍然没有活动，issue 将在一段时间后关闭。

我们非常重视用户的反馈，因此 bot 配置了很长的时间段，然后才将 issues 标记为 stale。

标有 todo 标签的 issues 永远不会被标记为 stale，因此此标签应分配给任何应保持打开状态的 issues，例如长期运行的功能请求。

PR 分流

Pull Requests 通常应分配一个类别标签，例如 bug、enhancement 或 BREAKING。这些标签用于在发行说明中对 PR 进行分类，如下面 介绍。

所有 PR 都应在合并之前至少进行一次审查。特别是，维护者通常应确保 PR 具有足够的单元测试来覆盖任何已修复的错误或新功能。

PR 通常使用 “squash and merge” 完成，以便保持清晰的线性历史记录，并使其更容易调试任何问题。

版本控制

SHAP 使用符合 PEP 440 的 MAJOR.MINOR.PATCH 版本控制方案。与 numpy 类似，SHAP 不 使用语义版本控制，并且从未进行过 major 版本发布。大多数版本会递增 minor，通常每隔一两个月发布一次。patch 版本有时会针对任何重要的错误修复发布。

考虑到 SHAP 是一个非常受欢迎的软件包，破坏性更改会谨慎进行。当进行破坏性更改时，PR 应标记 BREAKING 标签，以确保在发行说明中突出显示。弃用周期用于减轻对下游用户的影响。

GitHub 里程碑可用于跟踪给定版本需要完成的任何操作，例如与弃用周期相关的操作。

我们使用 setuptools-scm 从 git 历史记录中自动获取版本号。在构建时，版本号从 git 标签确定。

最低支持的依赖项

我们的目标是遵循关于最低支持的依赖项的 SPEC 0 约定。

• Python 版本的支持在其初始发布 3 年后停止。

• 核心软件包依赖项的支持在其初始发布 2 年后停止。

如果不会增加额外的维护负担，我们可能会支持 python 版本的时间略长于此窗口。

发布版本

我们尝试使用自动化来使发布过程可靠、透明和可重现。这也有助于我们更频繁地发布版本。

通过发布 GitHub Release 来发布版本，并标记适当递增的版本号。

发布版本后，wheels 将由 build_wheels GitHub action 自动构建并发布到 PyPI。此工作流程也可以随时手动触发，以对 cibuildwheel 进行 dry-run。

在版本发布之前，创建一个 GitHub issue 以进行版本发布，例如 [Meta issue] Release 0.43.0。这可以用于与其他维护者协调并同意发布版本。

建议的发布检查清单

- [ ] Dry-run cibuildwheel & test
- [ ] Make GitHub release & tag
- [ ] Confirm PyPI wheels published
- [ ] Conda forge published

conda 包在 单独的仓库 中管理。conda-forge bot 通常会在 PyPSA 包发布后的几个小时内自动向此仓库发出 PR，以更新 conda 包。

从 PR 标签生成发行说明

可以使用自上次版本合并以来的 PR 的标题和标签，由 Github 自动起草发行说明。有关更多信息，请参阅 GitHub 文档中关于 自动生成的发行说明 的内容。

生成的说明将遵循 .github/release.yml 中定义的模板，按标签将 PR 排列到子标题中，并排除 bot 制作的 PR。有关可用的配置选项，请参阅 文档。

为每个 PR 分配诸如 BREAKING、bug、enhancement 或 skip-changelog 之类的标签很有帮助，这样更改将显示在 notes 的正确部分下。它还有助于确保每个 PR 都有描述性名称。

可以在发布之前和之后编辑 notes，以删除不太可能引起用户高度关注的信息，例如维护更新。