贡献于 pythonot

首先，感谢您考虑为POT作贡献。

如何贡献

为POT做贡献的首选工作流程是分叉主仓库，克隆并在一个分支上进行开发。步骤：

  1. 通过点击页面右上角的“Fork”按钮来Fork 项目代码库。这会在您的GitHub用户账户下创建代码的副本。有关如何Fork代码库的更多详细信息，请参见本指南。

  2. 从你的GitHub账户克隆你的POT仓库到本地磁盘:

    $ git clone git@github.com:YourLogin/POT.git
$ cd POT

  3. 安装 pre-commit 钩子以确保您的代码格式正确：

    $ pip install pre-commit
$ pre-commit install

    这将安装在每次提交时运行的 pre-commit 钩子。如果钩子失败，提交将被中止。

  4. 创建一个 feature 分支来保存你的开发更改：

    $ git checkout -b my-feature

    始终使用 feature 分支。永远不要在 master 分支上工作是一个好习惯！

  5. 在你的特性分支上开发功能。使用 git add 添加更改的文件，然后 git commit 文件：

    $ git add modified_files
$ git commit

    以记录你在 Git 中的更改，然后使用以下命令将更改推送到你的 GitHub 账户：

    $ git push -u origin my-feature

  6. 按照这些指示从你的分支创建一个拉取请求。这将向提交者发送一封电子邮件。

(如果以上任何内容对你来说似乎是魔法，请在网上查阅Git 文档，或请教朋友或其他贡献者寻求帮助。)

拉取请求清单

我们建议在提交拉取请求之前，您的贡献遵循以下规则：

  • 遵循PEP8指南，这应该由pre-commit自动处理。

  • 如果您的拉取请求涉及某个问题，请使用拉取请求标题来描述该问题，并在拉取请求描述中提及问题编号。这将确保创建一个指向原始问题的链接。

  • 所有公共方法应具有信息丰富的文档字符串，并在适当时提供示例用法作为文档测试。

  • 如果您的拉取请求的标题前缀为 [MRG] （准备合并），则说明贡献是完整的并且准备好进行详细审查。 两位核心开发人员将审查您的代码，并在批准后将拉取请求的前缀更改为 [MRG + 1] 和 [MRG + 2]，使其符合合并条件。一个不完整的贡献——您期望在收到全面审查之前做更多工作——应前缀为 [WIP] （以表示正在进行的工作），并在成熟后更改为 [MRG]。WIP 可能对以下情况有用： 指示您正在从事某项工作，以避免重复工作， 请求对功能或 API 的广泛审查，或寻求合作者。 WIP 通常通过在 PR 描述中包含一个 任务列表 而受益。

  • 当添加额外功能时，在examples/文件夹中提供至少一个示例脚本。查看其他示例作为参考。示例应该展示新功能在实践中的实用性，如果可能的话，与POT中可用的其他方法进行比较。

  • 文档和高覆盖率的测试是确保增强功能被接受的必要条件。bug修复或新特性应该提供非回归测试。这些测试验证修复或特性的正确行为。通过这种方式，代码库的进一步修改可以确保与期望的行为一致。对于bug修复的情况，在PR提交时，这些测试应该在主代码库中失败，而在PR代码中通过。

  • 至少有一段叙述性文档，包含对文献的引用链接（尽可能提供PDF链接）以及示例。

您还可以使用以下工具检查常见的编程错误：

  • 所有的静态检查通过。您可以运行以下命令进行检查：

    $ pre-commit run --all-files

    这将对仓库中的所有文件运行预提交检查。

  • 所有测试均通过。您可以运行以下命令进行检查：

     $ pytest --durations=20 -v test/ --doctest-modules

对于包含性能分析、基准脚本和性能分析输出的贡献，将获得额外积分（请在邮件列表或GitHub问题中报告）。

提交错误报告

我们使用Github问题来跟踪所有的错误和功能请求；如果您发现了一个错误或希望看到某个功能的实现，请随时提出问题。

建议在提交之前检查您的问题是否符合以下规则：

  • 验证您的问题当前是否没有被其他 问题 或 拉取请求 处理。

  • 请确保所有代码片段和错误消息都格式化在适当的代码块中。 见 创建和突出显示代码块。

  • 请提供您的操作系统类型和版本号，以及您的 Python、POT、numpy 和 scipy 版本。您可以通过运行以下代码片段找到这些信息：

import platform; print(platform.platform())
import sys; print("Python", sys.version)
import numpy; print("NumPy", numpy.__version__)
import scipy; print("SciPy", scipy.__version__)
import ot; print("POT", ot.__version__)

  • 请具体说明涉及的估计器和/或函数，以及数据的形状；请包含一个可重现的代码片段或链接到gist。如果抛出异常，请提供回溯信息。

新贡献者提示

开始为POT贡献的一个好方法是从问题追踪器中的简单问题列表中选择一个项目。解决这些问题可以让你在没有太多先前知识的情况下开始为项目做贡献。你在这一领域的帮助将受到经验丰富的开发者的高度赞赏，因为这有助于他们腾出时间专注于其他问题。

文档

我们很高兴接受任何形式的文档：函数文档字符串， reStructuredText文档（像这个），教程等。 reStructuredText文档存放在源代码库的 doc/ 目录下。

您可以使用任何文本编辑器编辑文档，然后通过在 docs/ 目录中输入 make html 来生成 HTML 输出。或者，可以使用 make 快速生成不带示例图库的文档，使用 make html-noplot。生成的 HTML 文件将放置在 docs/build/html/ 中，并可以在网络浏览器中查看。

要构建文档，您需要 sphinx, matplotlib和 pillow。

当您编写文档时，在数学细节和算法细节之间保持良好的妥协是很重要的，并向读者提供关于算法所做的事情的直观理解。最好始终以一小段对方法对数据作用的笼统解释和一个图示（来自示例）作为开始。

本贡献指南受到scikit-learn团队指南的强烈启发。