贡献指南#

欢迎！所以，你有兴趣为STUMPY做第一次开源贡献？我们很高兴能与你一起开启这段旅程。以下是一些帮助你入门的事项。

Git 和 GitHub#

您不需要一个 GitHub 账户来使用 STUMPY，但是如果您想进行代码或文档贡献，则需要一个账户。这个 GitHub 账户将允许您为许多最受欢迎的开源项目做出贡献。此外，它还将为您提供一个存储、跟踪和协调自己项目进展的地方。GitHub 是一个 remote repository，用于版本控制系统 git。 Git 是一种版本控制工具，通过构建有向无环图（方便我们创建 branches、revert 更改，并识别 conflicts）来跟踪项目中的更改。您可以在本地计算机上使用 git，但是当您想保存工作或与其他团队成员协作时，您 push 您的工作到一个 remote 存储库。在这种情况下，这个 remote 将是 GitHub。

考虑到所有这些，你还需要安装 git。

警告：不要混淆 git 和 GitHub。Git 是一个用于版本控制的工具。GitHub 是一个用于 git 项目的在线平台，作为远程仓库。

清单：

  • 创建 GitHub 账户

  • 安装 Git

查找你的贡献#

您决定要贡献，但如何接手一个新项目并找出您可以提供帮助的地方呢？这就像试图插入一个已经进行了几个月（或几年）的对话，往往会让人感到望而生畏。如果您之前使用过该项目，您会对其结构和API更加熟悉，但您可能还没有“窥见幕后”。最好的起点是问题列表。这些是其他人提出的功能请求/更改/错误。请随意浏览该列表，以了解项目中正在进行的所有工作。通常，维护者会有一个标签系统来组织问题。这些标签可能包括像documentation或enhancement这样的内容。对于新贡献者，许多项目都有良好的第一个问题标签。

您下一个要访问的地方应该始终是 CONTRIBUTING.md。在这里，维护者概述了他们对贡献者的任何指导，

如果您点击任何问题，您会看到相关讨论的运行历史。这作为该特定问题的思考记录。对于某些问题，您可能会看到正在进行的对话。在其他问题中，您可能只会看到最初的问题。这是您与维护者进行对话的机会。如果您发现一个感兴趣的开放问题，并且认为自己能够解决它，请随时留言。请记住，维护者也是人，在STUMPY，他们很高兴帮助新的贡献者。以下是一个潜在消息的示例：

这是第一次贡献！我看到这个问题与一个由不正确的变量名称导致的错误有关。这在你看来是否正确？如果是的话，我想处理这个问题并提交一个拉取请求来修复它。

此消息有几个作用。它表明您对该问题做了一些研究（表现出对维护者时间的尊重），获取他们的意见（帮助您解决问题），并确保他们将接受拉取请求（节省您的时间/精力）。记住您正在参与一个正在进行的谈话吗？有时，基于包中其他地方发生的更改，一个问题可能会变得无关或过时。像这样的简短说明让维护者知道您将继续处理这个问题，并确认它仍然是一个有价值的问题。

警告：如果你能察觉到其他人正在积极处理一个问题，千万不要介入。

清单：

  • 识别一个问题

  • 阅读 CONTRIBUTING.md

  • 在问题中发布您的提案

设置您的分支#

好的，所以您已经选择了一个需要解决的问题，并且维护者很高兴得到您的帮助。现在，让我们开始工作吧！

首先，您需要创建一个仓库的副本，以便您可以在其上进行操作；这称为一个 fork。这里是关于 forking a repository 的说明。现在您拥有一个与您的 GitHub 账户关联的副本。

接下来，您需要 clone 这个代码库的副本。这只是将其下载到您的计算机上，以便您可以对其进行操作。这里是 克隆代码库 的说明。记住 克隆您的分叉而不是 STUMPY 是非常重要的。

然后，您需要创建一个 branch。这里是 git 分支工作原理 的概述，但如果您在命令行中工作，那么您可能需要输入 git checkout -b branch_name。在这种情况下，branch_name 应该替换为描述您正在进行的更改的内容，例如 change_incorrect_variable 或 document_x。

现在，您在项目中所做的任何更改都会反映在您的分支中。稍后，您会希望将您的更改 合并 到主 STUMPY 存储库中（以便每个人都能从您的贡献中受益）。您的分支反映了所有这些更改。

警告：在进行任何更改之前，请创建您的分支。

清单：

  • 将 STUMPY 分叉到您的帐户

  • 克隆您分叉的本地副本

  • 为您的工作创建一个分支

遵循 CONTRIBUTING.md 指导#

开源的一个巨大好处是能够与来自世界各地的开发者合作。然而，您可以想象，将他们的贡献合并成一个一致的代码库，同时保持一致性可能会很有挑战性。幸运的是，最近在自动化工具方面的进展使这变得容易多了。还记得 CONTRIBUTING.md 吗？在提交一个 pull request 之前，我们有几件事想要确保完成。

首先，如果您实现了一个新特性或更改了现有特性，那么您也有责任提供单元测试。这通常可能与特性一样多的工作，因此请确保考虑到这一点。

接下来，运行 flake8 和 black。 flake8 是一个检查代码风格和质量的工具。 black 会进行必要的更改以确保代码格式的一致性。

清单：

  • 编写/更新任何单元测试

  • 运行 black --exclude=".*\.ipynb" --extend-exclude=".venv" --diff ./ 以重新格式化您修改的任何python文件

  • 运行 flake8 --extend-exclude=.venv ./ 来在您提交 pull request 之前识别任何格式错误

  • 运行单元测试。在 STUMPY 中，您将运行 ./setup.sh dev && ./test.sh

设置您的环境#

在进行新项目时，通常会有依赖关系。为了隔离不同项目之间的依赖关系，使用虚拟环境是一个好习惯。STUMPY 支持 venv 和 conda。在创建和激活这两种虚拟环境后，您安装的任何依赖关系都将被隔离（因此它们不会破坏您系统上的其他内容）。

首先，如果您使用的是 venv，那么您可以使用方便的 ./setup.sh dev 安装 STUMPY 及其所有依赖项。如果您在 conda 环境中构建 STUMPY，您可以考虑使用 ./conda.sh shell 脚本，它将自动帮助您安装 STUMPY 开发所需的所有依赖项。

确保一切正常运行的一个好方法是运行单元测试。对于 STUMPY，我们有脚本来帮助您做到这一点。您将运行 ./setup.sh dev && ./test.sh。在某些情况下，您可能会注意到 STUMPY 的卸载消息，但不要担心。这发生在您之前安装过 STUMPY 的情况下，因为 ./setup.sh dev 命令首先卸载任何现有版本的 STUMPY，然后它将从源代码重新安装（本地克隆的开发版本）。因此，一切应该都准备好了。

理想情况下，您将看到出色的 STUMPY 测试覆盖率通过。如果出现故障或中断，那么您可能有缺失依赖的问题。没有什么比在您进行更改 之后 发现这个问题更糟糕了。

如果所有测试都通过，那么您就知道您拥有一个可用的STUMPY副本来开始您的开发。继续实现您的功能或更改吧！

清单：

  • 创建一个虚拟环境

  • 安装依赖

  • 运行单元测试

将您的代码推送到GitHub#

现在你的 fork 包含了符合 STUMPY 格式标准的更新代码和单元测试。如果你熟悉 git 或者在多台工作站之间进行过工作，你可能已经将你的 commits 推送 到 GitHub 了。如果没有，那么现在就是时候了！

当你在处理更改时，你可能一直在保存文件。这些更改保存在你的本地机器上，但没有在版本控制中更新。要做到这一点，你需要 git add （“嘿 git，请跟踪这些文件”）， git commit -m （“嘿 git，此时，我想保存”）和 git push（“嘿 git，拿上最后一次提交并移动到 GitHub”）如 这里 所描述。记得 写一个好的提交信息。

注意： 尽量保持你的提交小而易于理解。一条好的经验法则是每次提交保持在50行代码以内（不包括文档字符串）。

警告：如果这是您第一次使用 git，它可能会提醒您有关全局设置的警告。幸运的是，该警告会告诉您如何修复它。

清单：

  • git add your_file

  • git commit -m '伟大的 提交 信息'

  • git push

将你的分支与父存储库同步#

在您进行开发分支工作的同时，STUMPY 仓库可能会有新的更改，而您的分叉没有这些更改。因此，建议在提交拉取请求之前，将您的分叉与其父仓库同步。有关更多信息请参阅Github 文档。

清单（通过Github获取上游）：

  • 将您的分支与上游/父级代码库同步（见下面的截图）

  • git checkout main

  • git pull

  • git checkout branch_name

  • git merge main

  • 运行单元测试: ./setup.sh dev && ./test.sh

清单（在本地抓取上游）：

  • git fetch upstream

  • git checkout main

  • git merge upstream/main

  • git checkout branch_name

  • git merge main

  • 运行单元测试： ./setup.sh dev && ./test.sh

Fetch Upstream Fork

将主分支合并到开发分支的指示

  1. 打开终端

  2. 将当前工作目录更改为您的本地开发存储库（例如，cd Git/stumpy_dev.git）

  3. 查看您的本地开发分支（例如，git switch some_new_feature）

  4. 提交您本地开发分支的所有更改（例如，git add some_file.py 和 git commit）

  5. 从上游仓库获取分支及其各自的提交（例如，git fetch upstream）

  6. 查看您分支的本地默认分支（例如，git checkout main）

  7. 将来自上游默认分支的更改合并 - 在这种情况下，上游/main - 到您的本地默认分支（例如，git merge upstream/main）。这将使您分叉的默认分支与上游仓库同步，而不会丢失您的本地更改。

  8. 如果您的本地主分支没有任何唯一的提交，Git将执行快速前进。否则，如果您的本地主分支有唯一的提交，您可能需要解决冲突。请注意，这不会影响您的开发分支！

  9. 接下来，切换到你的开发分支（例如，git switch some_new_feature）

  10. 最后，将主分支合并到你的开发分支中（例如，git merge main）

    • 您可能会看到如下内容，如果是这样，您需要打开标记为 CONFLICT 的文件并解决合并冲突。一旦完成，您需要提交更改并将提交推送（例如，git push）回 Github。

git merge main
Auto-merging stumpy/aamp_stimp.py
Auto-merging stumpy/core.py
Auto-merging stumpy/mpdist.py
CONFLICT (content): Merge conflict in stumpy/mpdist.py
Auto-merging stumpy/mstumped.py
CONFLICT (content): Merge conflict in stumpy/mstumped.py
Auto-merging stumpy/ostinato.py
Auto-merging stumpy/stimp.py
CONFLICT (content): Merge conflict in stumpy/stimp.py
Auto-merging stumpy/stumped.py
CONFLICT (content): Merge conflict in stumpy/stumped.py
Automatic merge failed; fix conflicts and then commit the result.
You will need to open up the files tagged with CONFLICT and resolve the merge conflicts. Once that's done, you will need to commit the changes and push the commit (e.g., git push) back to Github.

创建拉取请求#

现在，您的更新代码在 GitHub 上的 STUMPY 分支中。如果您希望 STUMPY 的维护者查看它，您需要创建一个 Pull Request。这里有说明 here，但 GitHub 也相当聪明。如果您在推送提交后不久导航到您的仓库分支，您通常会看到一条信息，比如“您最近推送的分支：X <比较 & 拉取请求>”。点击它将自动创建您的拉取请求。与提交一样，请确保给它一个描述性的名称。如果您的更改还不太工作，您可以在拉取请求前加上 [WIP]，表示“进行中的工作”。在您的拉取请求正文中，引用您正在处理的问题编号。GitHub 会自动将您的拉取请求链接到该问题。这将使得管理和交叉引用变得更加容易。

这是您与维护者交流的下一个机会。让他们知道您所做的更改以及是否需要任何帮助。此拉取请求将成为您与维护者在解决问题期间的持续对话。

持续集成系统自动确定合并拉取请求的适宜性。它们检查你的代码的格式、测试覆盖率和测试成功情况。在你提交拉取请求后，你会看到这些运行（作为你拉取请求中的评论）。如果它们失败，直到修复故障，你的代码将不会被合并。在 STUMPY 中，本地通过 flake8， black，和 ./setup.sh dev && ./test.sh 应该确保你的持续集成测试通过。

清单：

  • 创建一个拉取请求

  • 撰写一个有信息量的拉取请求消息

  • 监控您的拉取请求，以便进行持续集成检查和来自维护者的消息

处理您的拉取请求 (PR)#

维护者很可能会对你的PR有问题、意见或建议。这是一个合作的机会，应该对双方都有益。此外，知道你在处理已经提交的PR的同一问题时不需要创建新的分支是很有用的。相反，根据维护者的反馈，继续使用之前的分支来完善你的贡献。现在，你所做的每个并推送的提交都会自动反映在现有的拉取请求中。总之，如果你已经有一个开放的PR，那么在你在本地代码中做任何更改后，只需commit和push到你的分叉，如之前一样，这些更改将自动显示在相应的PR中。

警告：在每次更改后，请确保运行您的格式检查和单元测试。

清单：

  • 保持开放的心态，灵活应对，礼貌待人

合并！#

当贡献非常出色且经过打磨后，维护者将会 merge 它到 STUMPY 中。成功！

清单：

  • 庆祝

  • 去寻找另一个问题

出现问题时应该怎么办#

不可避免地，总会出现一些问题。请记住，您并不是一个人在战斗。开源社区是一个 社区，我们感谢您对 STUMPY 的关注和贡献。如果您的障碍与 GitHub 上已提交的问题有关，那么该问题可能是请求更多信息和帮助的好地方。如果您的障碍与您解决某个问题的方案有关，可以直接提交您的进展作为拉取请求。始终保持礼貌和耐心。

最终检查清单：#

  • 创建 GitHub 账户

  • 安装 Git

  • 识别一个问题

  • 阅读 CONTRIBUTING.md

  • 在问题中发布您的提案

  • 将 STUMPY 分叉到您的帐户

  • 克隆本地副本

  • 为您的工作创建一个分支

  • 创建一个虚拟环境

  • 安装依赖

  • 运行单元测试

  • 编写/更新任何单元测试

  • 运行 black --exclude=".*\.ipynb" --extend-exclude=".venv" --diff ./ 以重新格式化您修改的任何python文件

  • 运行 flake8 --extend-exclude=.venv ./ 来在您提交 pull request 之前识别任何格式错误

  • 运行单元测试。在 STUMPY 中，您将运行 ./setup.sh dev && ./test.sh

  • git add your_file

  • git commit -m '伟大的 提交 信息'

  • git push

  • 创建一个拉取请求

  • 撰写一个有信息量的拉取请求消息

  • 监控您的拉取请求，以便进行持续集成检查和来自维护者的消息

  • 保持开放的心态，灵活应对，礼貌待人

  • 庆祝

  • 去找另一个问题