跳转至

贡献

原文:https://web3py.readthedocs.io/en/stable/contributing.html

感谢您对 Web3.py 的关注！请继续阅读，了解什么是有帮助的，以及如何去做。如果你中途遇到困难，可以在 Python Discord 服务器中寻求帮助。

如何提供帮助

无代码:

  • 回答 GitHub 问题、堆栈溢出或 Python Discord 服务器中的用户问题。
  • 编写或记录教程内容。
  • 改进我们的文档(包括打字错误的修复)。
  • 在 GitHub 上打开一个问题来记录一个 bug。包括尽可能多的细节，例如，如何重现问题和任何异常消息。

带代码:

  • 修复在某个问题中报告的错误。
  • 添加已在问题中记录的功能。
  • 添加缺失的测试用例。

警告

在你开始工作之前，一定要问一下是否需要改变，或者让我们知道你打算做些什么！我们不想把你的时间浪费在我们不能接受的改变或重复的努力上。

您的开发环境

注意

强烈建议使用虚拟环境来最大限度地减少依赖性问题。使用模式见本文。

所有的拉请求都是从仓库的一个分支发出的；使用 GitHub UI 创建一个分支。Web3.py 依赖于子模块，所以当您将您的 fork 克隆到您的本地机器时，包括--recursive标志:

$ git clone --recursive https://github.com//web3.py.git $ cd web3.py

最后，安装所有开发依赖项:

$ pip install -e ".[dev]"

使用 Docker

不要求在 Docker 中开发，但是如果你喜欢那个工作流，使用 docker-compose.yml 文件中提供的沙箱容器。

要启动测试环境，请运行:

$ docker-compose up -d

这将构建一个 Docker 容器，设置一个运行 Python 测试代码的环境。

注意

这个容器没有安装 go-ethereum ，所以您不能运行 go-ethereum 测试套件。

要从本地机器运行 Python 测试:

$ docker-compose exec sandbox bash -c 'pytest -n 4 -f -k "not goethereum"'

通过使用 bash -c 前缀，您可以在 Docker 容器中运行任意命令。

$ docker-compose exec sandbox bash -c ''

或者，如果您想要打开容器的会话，请运行:

$ docker-compose exec sandbox bash

代码风格

我们重视代码的一致性。为了确保您的贡献符合该项目中使用的风格，我们鼓励您阅读我们的风格指南。

类型提示

这个代码库利用了类型提示。类型提示使防止某些类型的错误变得容易，支持更丰富的工具，并增强文档，使代码更容易理解。

除了测试之外，所有新代码都需要包含类型提示。

所有参数以及函数的返回类型都应该是类型化的，除了下面的例子中的self和cls。

def __init__(self, wrapped_db: DatabaseAPI) -> None: self.wrapped_db = wrapped_db self.reset()

运行测试

探索代码库的一个好方法是运行测试。

首先，安装测试依赖项:

$ pip install -e ".[tester]"

您可以使用以下工具运行所有测试:

$ pytest

然而，运行整个测试套件需要很长时间，并且通常不切实际。通常，您只想运行一个子集，比如:

$ pytest tests/core/eth-module/test_accounts.py

您可以使用tox来运行给定 Python 版本的所有测试:

$ tox -e py37-core

林挺也是由 CI 演出的。通过在本地检查林挺错误，您可以节省一些时间:

$ make lint

作为 CI 检查的一部分，每个 pull 请求都必须通过完整的测试套件，理解这一点很重要。这个测试套件将在任何打开或更新拉请求的时候在 CI 中运行。

写作测试

我们强烈鼓励贡献者为他们的代码编写好的测试，作为代码评审过程的一部分。这有助于确保您的代码正在做它应该做的事情。

我们强烈建议您使用我们现有的测试来指导我们的测试，并确保测试的一致性。我们使用pytest进行测试。有关更具体的 pytest 指南，请参考 pytest 文档。

在pytest范围内，conftest.py文件用于模块间共享的公共代码，这些模块与特定的conftest.py文件位于同一目录下。

单元测试

单元测试意味着测试代码库的较小块(或单元)的逻辑，而不必连接到客户端。大多数情况下，这意味着测试选定的方法本身。它们旨在测试您的代码的逻辑，并确保您从选定的输入中获得预期的输出。

我们的单元测试位于/tests目录中适当命名的子目录下。单元测试的核心在/tests/core下进行。在选择添加单元测试的位置时，尽最大努力遵循现有的结构。

集成测试

我们的集成测试套件设置位于/tests/integration目录下。集成测试套件依赖于我们所谓的“fixture”(不要与 pytest fixtures 混淆)。这些 zip 文件设备也位于/tests/integration目录中，它们被配置为运行我们测试的特定客户端，以及一个 genesis 配置，该配置为我们的测试提供了一些预先确定的有用对象(如未锁定的、预加载的帐户),以便能够与客户端交互并运行我们的测试。

尽管设置驻留在/tests/integration中，但是我们的集成模块测试是跨/web3/_utils/module_testing中的不同文件编写的。测试写在那里，但是运行配置存在于/tests/integration/的不同文件中。父目录/integration保存了一些所有客户端测试共享的公共配置，而/go_ethereum目录保存了各个客户端测试共享的公共代码。

  • 客户端目录中的文件包含所有供应商测试(http、ipc 和 ws)共享的代码。这主要用于覆盖跨越所有供应商的测试。
  • conftest.py这些目录中的文件包含了大部分代码，这些代码可以被conftest.py文件所在目录中的所有测试文件使用。这主要是用来存放在我们的测试中共享的 pytest fixtures。更多信息请参考夹具上的 pytest 文档。
  • test_*client*_*provider*.py(例如test_goethereum_http.py)文件是客户和供应商特定的测试配置存在的地方。这主要用于覆盖特定于各个客户端的供应商类型的测试。

人工测试

要在另一个上下文中导入和测试 Web3.py 的未发布版本，您可以从您的开发目录中安装它:

$ pip install -e ../path/to/web3py

证明文件

好的文档会导致更快的采用和更满意的用户。请查看我们关于如何为 Python 以太坊生态系统创建文档的指南。

拉请求在https://web3py--<pr-number>.org.readthedocs.build/en/<pr-number>/生成它们自己的最新文档预览。

拉取请求

尽早提出拉取请求是个好主意。“拉”请求代表讨论的开始，不一定是最终完成的提交。

参见 GitHub 的文档了解如何处理 pull 请求。

一旦您发出了一个 pull 请求，查看一下 GitHub 界面中的 Circle CI 构建状态，确保所有测试都通过了。一般来说，没有通过 CI 构建的拉请求不会得到审查，除非明确提出请求。

如果拉请求引入了应该反映在发行说明中的变更，请添加一个新闻片段文件，如这里的所解释的。

如果可能，对发行说明文件的更改应该包含在引入特性或错误修复的提交中。

生成新装置

我们的集成测试利用了 Geth 专用网络。当引入新版本的客户端软件时，应该生成新的夹具。

在生成新的 fixtures 之前，确保您已经安装了测试依赖项:

$ pip install -e ".[tester]"

注意

“设备”是一个预先同步的网络。它是配置和运行客户机、部署测试合约以及保存测试 Web3.py 功能的结果。

获取固定装置

  1. 在本地机器上安装所需的 Geth 版本。为此，我们推荐使用 py-geth ，因为它使您能够轻松管理 geth 的多个版本。

    注意py-geth也需要更新以支持每个新的 Geth 版本。向 py-geth 添加新的 Geth 版本非常简单；查看模板的过去提交。

    如果 py-geth 有您需要的 geth 版本，请在本地安装该版本。例如:

    py $ python -m geth.install v1.10.23

  2. 指定 Geth 二进制文件并运行 fixture 创建脚本(从 web3.py 目录中):

    py $ GETH_BINARY=~/.py-geth/geth-v1.10.23/bin/geth python ./tests/integration/generate_fixtures/go_ethereum.py ./tests/integration/geth-1.10.23-fixture

  3. 这个脚本的输出是您的 fixture，一个 zip 文件，现在存储在/tests/integration/中。更新/tests/integration/go_ethereum/conftest.py文件，指向这个新的夹具。删除旧设备。

  4. 进行测试。为了确保测试在本地使用正确的 Geth 版本运行，您可以再次包含GETH_BINARY环境变量。

通过每夜构建进行 CI 测试

有时候，您会希望 CI 针对 Geth 的未发布版本运行测试套件，例如，测试即将到来的硬分叉更改。下面描述的工作流仅用于测试，即，打开一个 PR，让 CI 运行测试，但是只有在 Geth 版本发布后，或者您有一些不需要从不稳定的客户端构建测试装置的解决方法时，才应该将更改合并到 master 中。

  1. 根据需要配置tests/integration/generate_fixtures/go_ethereum/common.py。
  2. Geth 自动编译合并到代码库中的每个提交的新版本。从开发构建下载所需的构建。
  3. 构建您的测试夹具，通过GETH_BINARY传递您刚刚下载的二进制文件。不要忘记更新/tests/integration/go_ethereum/conftest.py文件以指向您的新夹具。
  4. 我们的 CI 运行在 Ubuntu 上，所以下载相应的 64 位 Linux develop build ，然后将其添加到您的 Web3.py 目录的根目录下。重命名二进制文件custom_geth。
  5. 在.circleci/config.yml中，更新依赖geth_steps的作业，改为使用custom_geth_steps。
  6. 创造一个公关，让 CI 做它的事。

放

每次发布前的最终测试

在发布新版本之前，构建并测试将要发布的包。有一个脚本可以在本地构建和安装轮子，然后为冒烟测试生成一个临时的 virtualenv:

$ git checkout master && git pull $ make package # in another shell, navigate to the virtualenv mentioned in output of ^ # load the virtualenv with the packaged web3.py release $ source package-smoke-test/bin/activate # smoke test the release $ pip install ipython $ ipython >>> from web3.auto import w3 >>> w3.isConnected() >>> ...

验证最新文档

要预览将要发布的文档:

$ make docs

预览发行说明

$ towncrier --draft

编译发行说明

在确认发布包看起来没问题之后，编译发布说明:

$ make notes bump=$$VERSION_PART_TO_BUMP$$

您可能需要在提交之前修复任何损坏的发行说明片段。继续运行make build-docs直到它通过，然后提交并继续。

将发布推送到 GitHub 和 PyPI

在提交编译好的发行说明并将它们推送到主分支之后，发布一个新版本:

$ make release bump=$$VERSION_PART_TO_BUMP$$

要碰撞哪个版本零件

本次回购的版本格式为{major}.{minor}.{patch}表示稳定，{major}.{minor}.{patch}-{stage}.{devnum}表示不稳定(stage可以是 alpha 或 beta)。

在释放过程中，指定要撞击的部分，如make release bump=minor或make release bump=devnum。

如果你在 alpha 版本中，make release bump=stage会跳到 beta。如果你是测试版，make release bump=stage会撞上稳定版。

要在当前版本稳定的情况下发布不稳定版本，明确指定新版本，比如make release bump="--new-version 4.0.0-alpha.1 devnum"。

回到顶部