贡献代码#

为 Feature-engine 贡献代码既有趣又简单。如果你想进行代码贡献，可以查看 问题追踪器 中已经请求并需要的功能。或者，你可以创建一个包含你希望在 Feature-engine 中看到的新功能的问题，然后逐步实现它。

贡献工作流程#

典型的贡献工作流程如下：

  1. 建议 新功能或 认领 问题追踪器 中的问题。

  2. 在问题中提及 你正在“处理中”。

  3. Fork 仓库到你的 GitHub 账户。

  4. 克隆 你的分支到你的本地计算机。

  5. 设置 开发环境。

  6. 创建 一个新分支，命名为你的功能名称

  7. 代码 功能、测试，并更新或添加文档。

  8. 提交 更改到你的分支。

  9. 将您的更改从您的分支提交到主仓库，创建一个 Pull Request (PR)。

  10. 测试 代码。

  11. 回顾 代码与我们一起。

  12. 进行 更改 并将它们提交到你的分支，使用在第5步中创建的相同分支。

  13. 当准备就绪时，我们将 合并 您的贡献到 Feature-engine 的源代码库中。

为了避免额外的工作或重复，从一开始就进行沟通非常重要，这样我们可以共同建立一个清晰的认识，了解您希望如何参与以及完成任务所需的内容。这对于大量的代码添加尤为重要。

在文档的其余部分，我们将更详细地描述步骤3到13。

Fork 仓库#

当你分叉仓库时，你会在你的Github账户中创建Feature-engine源代码的副本，你可以对其进行编辑。要分叉Feature-engine的仓库，请点击 Feature-engine的仓库 右上角的 fork 按钮。

../_images/fork.png

克隆仓库#

一旦你分叉了仓库，将其克隆到你的本地机器。

  1. 将你的分支克隆到本地机器:

    $ git clone https://github.com/<YOURUSERNAME>/feature_engine

  2. 从主 Feature-engine 仓库中设置一个 upstream 远程，以便你可以拉取最新的代码更改:

    $ git remote add upstream https://github.com/feature-engine/feature_engine.git

  3. 检查远程设置是否正确:

    $ git remote -v

你应该看到你的分支（origin）和主仓库（upstream）链接到你的本地副本:

origin    https://github.com/YOUR_USERNAME/feature_engine.git (fetch)
origin    https://github.com/YOUR_USERNAMEfeature_engine.git (push)
upstream  https://github.com/feature-engine/feature_engine.git (fetch)
upstream  https://github.com/feature-engine/feature_engine.git (push)

请记住，Feature-engine 正在积极开发中，因此您可能需要定期更新您的分支。请参见下方如何 保持您的分支最新。

设置开发环境#

在创建了仓库的本地副本后，你需要设置开发环境。设置开发环境将确保你拥有开发所需的所有库，不多也不少。这些库包括 Feature-engine 依赖项，如 Pandas、NumPy 和 Scikit-learn，以及 软件开发库，如 pytest、mypy、flake8、isort 和 black。

虽然创建虚拟环境是可选的，但强烈建议这样做。虚拟环境是一个“独立的空间”，您可以在这里安装 Feature-engine 的依赖项。要创建虚拟环境，请使用您选择的任何虚拟环境工具。一些例子包括：

  1. venv 是一个用于创建虚拟环境的Python模块。

  2. conda 环境

在前面的链接中，您可以找到关于如何创建环境的详细信息。我们在下面提供了一些指导方针。

venv#

如果你使用 venv，从 Windows 命令提示符或 Mac 终端，创建并激活环境如下:

python -m venv /path/to/new/virtual/environment

例如，我会这样做:

python -m venv Documents/Repositories/envs/featureengine

其中，“featureengine” 将是环境的名称，而 “Documents/Repositories/envs” 是创建环境的位置。

然后，要激活环境，请运行:

Documents/Repositories/envs/featureengine/Scripts/activate

Windows 用户注意： 你可能需要使用 而不是 /。

conda#

如果你使用的是Anaconda，从你的conda提示符中，创建并激活环境如下:

conda create --name myenv

其中“myenv”将是环境的名称，因此您可能希望将其更改为更有意义的名称。

然后，要激活环境，请运行:

conda activate myenv

安装依赖项#

现在，您已准备好安装所有依赖项，即 Feature-engine 使用的所有 Python 库。首先，导航到您的 Feature-engine 克隆目录:

$ cd feature_engine

现在，以开发者模式安装 Feature_engine:

$ pip install -e .

不要忘记在 -e 后面加上 .。这将把 Feature-engine 添加到你的 PYTHONPATH 中，以便你的代码编辑会自动被识别，并且每次代码更改后无需重新安装包。这也会安装 Feature-engine 的依赖项。

最后，安装测试和文档所需的额外依赖项:

$ pip install -r test_requirements.txt
$ pip install -r docs/requirements.txt

确保你的本地主分支与远程主分支保持最新:

$ git pull --rebase upstream main

如果你刚刚克隆了你的分支，你的本地主分支应该是最新的。如果你很久以前克隆了你的分支，可能主仓库已经有了一些代码变化。要将你的分支主分支与主仓库同步，请阅读下面的 保持你的分支最新 部分。

创建一个分支#

重要的是要创建一个新分支，不同于主分支，你将在其中编写你的更改。建议几乎永远不要在主分支上工作。

创建一个新分支，你将在其中开发你的功能:

$ git checkout -b myfeaturebranch

其中 “myfeaturebranch” 是你为你的分支选择的名称。

在创建特性分支时，有3点需要注意：

  1. 给分支起一个能标识你要构建的功能的名字。

  2. 确保你从主分支检出了你的分支。

  3. 确保你的本地主分支已与上游主分支同步更新。

编写你的功能代码#

现在，你可以开始进行代码修改了。当你开发新功能、修复错误或进行任何代码贡献时，有几件事需要考虑：

  1. 定期将代码提交到本地的分支。

  2. 给你的提交提供清晰的描述，表明每次提交中进行了哪些更改（使用现在时态）。

  3. 尝试定期将更改推送到你的分支，以避免丢失你的修改。

提交#

进行小改动并立即提交。这样更容易追踪哪些内容被更改了。要提交更改，请执行以下操作:

$ git add .
$ git commit -m "my commit message"

并确保在现在时态中包含一个信息丰富但简洁的提交消息，例如“修复插补错误消息中的样式”。

之前的命令将提交所有有更改的文件。如果你想只提交1或2个文件，可以这样做:

$ git add file1.py file2.py
$ git commit -m "my commit message"

重要的是你只提交与你的功能相关的文件，而不是其他可能因意外更改的文件，例如通过代码样式（更多内容请参见下面的 测试代码）。

进行几次提交后，将您的更改推送到您的分支:

$ git push origin myfeaturebranch

这将会在你的远程分支中自动创建一个名为“myfeaturebranch”的分支，其中包含你所有的更改。

提交拉取请求#

推送第一次更改后，转到你在 Github 上的 fork。你将看到你刚刚推送的分支，并且旁边有一个创建 PR（拉取请求）的按钮。继续从你的功能分支创建一个到 Feature_engine 的 主分支 的 PR。在 PR 消息中，描述 PR 的总体目标，如果它解决了某个问题，请在消息中链接该问题。这将通知我们你的更改。

别担心，你可以继续对分支进行更改并提交更多代码。基本上，你需要根据需要重复这些步骤:

$ git add .
$ git commit -m "my commit message"
$ git push origin myfeaturebranch

一旦你认为你的代码准备好接受审查，请在PR中留言说“请审查”或类似的内容。

创建文档字符串#

如果你正在编写一个全新的类，请确保你遵循我们的 编写文档字符串的指南。

测试代码#

你提交的代码必须通过你添加的任何测试以及库中所有当前的测试。当你第一次提交PR时，测试会自动触发，然后每次你向PR提交新更改时都会触发。重要的是，当你要求我们审查时，测试必须通过。

我们有以下测试：

  1. 功能性，使用 pytest

  2. 代码风格，使用 flake8

  3. 类型提示，使用 mypy

  4. 使用 sphinx 的文档。

  5. 使用覆盖率进行覆盖

在接下来的段落中，我们将带您了解如何测试上述每一项。

测试功能#

我们使用 pytest 来创建和运行我们的测试。如果你按照我们之前描述的方式设置了开发环境，你应该已经安装了 pytest。或者，从 Windows 命令提示符或 Mac 终端运行:

$ pip install pytest

你现在可以从命令行界面运行测试。确保你在 feature-engine 文件夹内。然后运行:

$ pytest

这些命令将运行测试文件夹中的所有测试脚本。这将需要几分钟时间。

或者，您可以按如下方式运行特定脚本:

$ pytest tests/test_encoding/test_onehot_encoder.py

上一个命令将仅运行单热编码器的测试。

如果你直接测试你创建的代码，速度会更快，在这种情况下你可以这样做:

$ pytest tests/test_my_new_feature_folder/test_my_new_feature.py

其中 test_my_new_feature.py 是你的测试脚本的名称，它位于 test_my_new_feature_folder 中。

如果你使用的是Pycharm，这会更加简单：

  1. 在你的项目目录（包含所有文件和脚本的目录）中，右键点击“tests”文件夹。

  2. 选择“在测试中运行 pytest”。

这将运行所有测试。

要运行您的特定测试：

  1. 找到您的测试文件

  2. 右键点击测试文件。

  3. 选择“在测试中运行 pytest”。

很棒，不是吗？

通过上述步骤，您还可以“点击”您的单个测试脚本并仅运行这些测试。

代码覆盖率#

我们使用 coverage 来测试我们测试的覆盖范围。要评估代码覆盖率，您需要使用 coverage 运行 pytest:

$ coverage run -m pytest

然后，你可以像这样可视化报告:

$ coverage report

如果你发现你正在处理的任何类中缺少覆盖率，尝试添加测试以提高覆盖率。我们的目标是达到97%。

测试代码风格#

我们遵循 PEP8 ，并且我们的代码行保持在88个字符以内。在测试代码风格之前，确保使用 **black** 和 **isort** 自动修复任何可能不符合PEP8的内容。

如果你按照我们之前描述的方式设置了开发环境，你应该已经安装了这些库。或者，从Windows命令提示符或Mac终端运行:

$ pip install black
$ pip install isort

然后，您可以通过运行以下命令按字母顺序对导入进行排序:

$ isort my_new_script.py

你可以通过运行以下命令来修复代码风格:

$ black my_new_script.py

你需要在代码文件和测试文件上运行 isort 和 black。

Black 和 isort 可能会对你的文件进行修改。别忘了提交这些更改:

$ git add my_new_script.py
$ git commit -m "fix code style"
$ git push origin my_feature_branch

现在，你可以继续测试你的脚本是否通过了代码样式测试。为此，请从命令行执行:

$ flake8 my_new_script.py

如果 flake8 测试通过，你就可以继续了。否则，你会收到一个错误，指出哪一行代码不符合编码规范。

测试类型提示#

我们使用 Typehint 。为了测试类型提示，我们使用 **mypy** 。

如果你按照我们之前描述的方式设置了开发环境，你应该已经安装了mypy。或者，从Windows命令提示符或Mac终端运行:

$ pip install mypy

现在，您可以通过运行以下命令来测试类型提示:

$ mypy feature_engine

一些需要注意的事项：

  • 我们仅在代码库中使用类型提示，而不在测试中使用。

  • 你需要在整个模块上运行 mypy，而不仅仅是你的脚本。

否则，你很可能会遇到错误。

测试文档#

如果在运行 pytest、black 和 mypy 后没有出现错误，你只需要测试文档是否能正确构建。

要执行此操作，首先确保您已安装所有文档依赖项。如果您按照我们之前描述的方式设置了环境，它们应该已安装。或者，从Windows命令提示符或Mac终端运行:

$ pip install -r docs/requirements.txt

在运行前一个命令时，请确保你在 feature_engine 模块内。

现在，你可以继续构建文档:

$ sphinx-build -b html docs build

这将触发文档的构建，文档将以html格式存储在仓库的“build”文件夹中。你可以用浏览器打开这些文件。但重要的是，在构建过程中不要出现任何红色警告。

使用 tox#

在 Feature-engine 中，我们使用 tox 来自动运行所有测试。如果你想在本地使用 tox 运行所有测试：

  1. 在你的开发环境中安装tox:

    $ pip install tox

  2. 确保你在仓库文件夹中，或者:

    $ cd feature_engine

  3. 在tox中运行测试:

    $ tox

只需输入 tox，就会自动触发功能测试、代码样式测试、类型提示测试和文档测试。这些测试将测试整个 Feature-engine 生态系统，而不仅仅是您的新脚本，因此会更耗时。

如果测试通过，代码处于最佳状态 :)

需要注意的几点：

Tox 在我们的 Python 版本 3.6、3.7、3.8 和 3.9 中运行测试。然而，它只能在你本地安装的版本中运行测试。其他版本将会失败。这没关系。只要你安装的 Python 版本中的测试通过，你就可以继续。

Tox 可能会修改一些与你的功能无关的本地文件。请 不要 将这些文件添加到你的 PR 中。

如果你想了解更多关于 tox 的信息，请查看这个 链接。如果你想了解我们为什么更喜欢 tox，这篇文章 文章 会告诉你一切 ;)

评审流程#

一旦你的贡献包含新代码、测试和文档，你可以在Pull Request的评论中提及请求审核。可能会有一些来回讨论，直到最终提交。我们将共同努力，使代码达到最终形态。

如果你觉得在初稿完成前需要澄清某些内容，或者有些测试无法通过，请不要犹豫在评论中提及，我们会尽力帮助。

我们旨在在一周内审查PR。如果由于某些原因我们无法做到，我们也会通过PR通知您。

一旦提交被审核并通过了持续集成测试，并且代码与Feature-engine的主分支保持最新，我们将准备好将您的贡献“压缩并合并”到Feature-engine的``main``分支中。“压缩并合并”将您的所有提交合并为一个提交，这有助于保持仓库历史记录的整洁。

一旦你的贡献被合并到主分支，你将被列为 Feature-engine 的贡献者 :)

合并拉取请求#

只有核心贡献者对仓库有写权限，可以审查和合并拉取请求。合并拉取请求时的一些提交信息偏好：

  • 确保使用“Squash and Merge”选项，以便创建一个易于理解的Git历史记录。

  • 保持提交标题简短且描述性强；确保它链接所有相关问题。

发布#

在您和其他贡献者向主分支添加了一些功能后，我们将把主分支合并到一个发布分支，例如 1.2.X，以将 Feature-engine 的新版本发布到 PyPI 和 conda-forge。

保持你的 Fork 更新#

当你使用分支进行协作时，更新你的分支以获取其他协作者所做的更改是非常重要的。

如果你的功能需要几周或几个月来开发，可能会发生其他贡献者对 Feature_engine 的主分支进行了新的代码更改。其中一些更改的文件可能与你正在处理的文件相同。因此，将上游主分支拉取并重新基于你的功能分支是非常重要的。为了保持你的分支最新：

  1. 查看你的本地主分支:

    $ git checkout main

如果你的特性分支有未提交的更改，它会要求你先提交或暂存这些更改。请参考我们上面描述的提交指南。

  1. 拉取并变基上游主分支到你的本地主分支:

    $ git pull --rebase upstream main

你的主分支应该是上游主分支的副本。如果不是，可能会出现一些冲突文件。你需要解决这些冲突并继续变基。

  1. 拉取更改到你的分支:

    $ git push -f origin main

上一个命令将更新你的 fork（远程），使得你的 fork 的主分支与 Feature-engine 的主分支同步。现在，你需要将主分支 rebase 到你的特性分支上。

  1. 查看你的特性分支:

    $ git checkout myfeaturebranch

  2. 将 main 变基到其上:

    $ git rebase main

再次，如果出现冲突，尝试解决它们并继续变基。

现在你可以继续开发你的功能了。

On this page
显示源代码