Faust 贡献指南：从报 Bug 到提交代码与发布的完整工作流

流处理消息队列后端【免费下载链接】faustPython Stream Processing项目地址https://gitcode.com/gh_mirrors/fa/faust点击查看免费下载Faust 是一个用于 Python 流处理的库主要与 Kafka 配合使用README.rst本文以仓库内的 docs/contributing.rst 为主线完整梳理 Faust 社区贡献的全流程如何安全地报告安全漏洞与普通 Bug、如何 Fork 仓库并搭建开发环境、如何运行测试套件与各类质量检查、如何遵循编码规范、如何为需要第三方库的新特性注册 extras 依赖以及维护者如何执行版本发布。读完本文你将能按 Faust 官方的协作规范独立完成从提交 Issue 到合入代码、甚至执行一次正式发布的全套操作并能对照仓库中的 Makefile、setup.py 与 tox.ini 理解每个命令背后的真实实现。贡献的基本原则Faust 的贡献文档开门见山地强调了两点核心理念贡献必须足够简单。文档明确写道The most important rule is that contributing must be easy and that the community is friendly and not nitpicking on details, such as coding style.不必苛求细节。即使你对编码风格不熟悉也没关系——合并者会在合入前帮你清理补丁你只需要尽量模仿你正在修改的代码周围的既有惯例即可。如果你只想提交一个很小的改动比如修一个拼写错误完全不需要通读整篇文档但如果你要报告 Bug 或提交代码则建议遵循下文各个小节的流程。这份规范还通过 Makefile 中的CONTRIBUTING_SRC指向docs/contributing.rst、contrib目标负责将其渲染为仓库根目录的 CONTRIBUTING.rst说明本文档同时是公开贡献页面的权威来源。报告 Bug安全漏洞绝不公开上报涉及安全的问题漏洞、敏感信息严禁提交到公开的 Issue 追踪器或任何公共渠道必须通过邮件发送到securityceleryproject.org。如果你需要加密提交文档提供了 Celery Security Team 的 PGP 公钥块见 docs/contributing.rst可用 GnuPG 加密邮件内容。这是社区通用的安全上报纪律在修复前公开漏洞细节可能危害所有下游用户。普通 Bug六步标准流程非安全类 Bug 的最佳上报途径是 Issue 追踪器相较于邮件列表能获得更及时的响应。文档给出了六步流程创建 GitHub 账号以便创建 Issue 并参与讨论。确认这确实是一个 Bug。如果是寻求使用帮助应改用邮件列表或 Slack 频道而不是提交 Issue。确认该 Bug 尚未被报告过。先搜索 Issue 追踪器如果已有相似 Issue补充你掌握的新信息帮助开发者定位问题。确认你使用的是最新版本。Bug 可能已被其他修复覆盖请升级到最新版本再复现。收集关于 Bug 的信息。绝大多数情况需要提供 Python traceback此外还应包含运行平台Windows、macOS、Linux 等、Python 解释器版本、Faust 版本以及相关依赖包版本。如果是竞态条件race condition或死锁traceback 往往难以获取或帮助有限可以尝试用系统工具抓取进程诊断数据Linux 用strace/ltrace/lsofmacOS 用dtrussBSD 用ktrace。运行faust report命令收集配置诊断信息这是 Faust 内置的排障命令$ faust -A proj report该命令会输出你的配置设置并尝试剔除已知的敏感键值但提交前仍应人工核对确保不包含 API token、认证凭据等机密信息。Issue 追踪器分工Faust 生态中的包有各自的追踪器Faust 自身的问题上报到 robinhood/faust 的 Issues而底层服务框架 Mode 的问题则上报到 ask/mode 的 Issues。如果拿不准问题根源在哪个包可以先询问邮件列表或直接使用 Faust 的追踪器。版本、分支与标签的治理模型理解 Faust 的分支与版本模型能帮你判断当前应该基于哪个分支开发也是维护者管理仓库的依据。版本号语义SemVer版本号由主版本major、次版本minor和发布号release组成遵循 SemVer 语义。正式版发布到 PyPI开发版仅以 git 标签形式存在于仓库。所有版本标签以v开头例如版本 0.8.0 对应的标签是v0.8.0。分支类型dev 分支git 称其为 master下一个版本开发的主战场。维护分支Maintenance branches以版本号命名例如 2.2.x 系列的维护分支叫2.2早期曾命名为releaseXX-maint。归档分支Archived branches仅用于保留历史命名为X.Y-archived理论上仍可为其提供补丁但版本不再被官方支持。特性分支Feature branches大型新功能在独立分支上开发命名没有硬性要求合并进发布分支后即被删除。可以通过仓库根目录的 Changelog.rst 判断任意分支的开发状态处于活跃开发的分支其顶部版本信息会带:status:元数据取值包括PLANNING处于实验与规划阶段。DEVELOPMENT活跃开发中但测试套件应保持通过、产品可用且可供用户试用。FROZEN分支已冻结不再接受新功能重点转为发布前尽可能充分地测试。发布标签发布标签格式为vX.Y.Z例如v2.3.1。预发布实验性版本带额外标识vX.Y.Z-id例如v3.0.0-rc1。实验性标签可能在正式发布后被移除。参与功能开发与补丁提交Faust 明确表态下列步骤都不强制甚至可以用邮件发送补丁遵守这些流程只是让维护者更省力、让你的改动更快被接受。1. Fork 并配置仓库先在 GitHub 上 Fork Faust 仓库然后克隆到本地并配置 upstream 以便同步上游$ git clone gitgithub.com:username/faust.git $ cd faust $ git remote add upstream git://github.com/robinhood/faust.git $ git fetch upstream拉取上游新改动时始终使用--rebase选项避免产生多余的合并提交污染历史$ git pull --rebase upstream master如果需要切换到远程的其它开发分支可以这样检出$ git checkout --track -b 2.0-devel origin/2.0-devel2. 搭建开发环境最省事的方式是直接使用 Makefile 的develop目标它会自动完成依赖安装、pre-commit 钩子安装和setup.py develop开发模式安装见 Makefile 中develop: reqs develop-hooks setup-develop的定义$ make develop如果你想手动安装至少要装上 git pre-commit 钩子$ make hooks对应实现是 Makefile 中的hooks: $(PRE_COMMIT) install。如果你还需要安装 C 扩展包括 RocksDB 绑定则改用make cdevelop$ make cdevelopcdedevelop在develop的基础上追加了reqs-ext即reqs-rocksdb reqs-fast reqs-uvloop三个目标见 Makefile分别安装 requirements/extras/rocksdb.txt、requirements/extras/fast.txt 与 requirements/extras/uvloop.txt 中声明的扩展依赖。3. 运行测试套件测试所需的完整依赖清单在 requirements/test.txt 中包括 pytest、pytest-asyncio、hypothesis、freezegun 以及 datadog/redis/statsd/yaml/prometheus 等 extras 依赖。稳定版与开发版都需要这些测试依赖$ pip install -U -r requirements/test.txt $ pip install -U -r requirements/default.txt然后执行测试$ py.test这会运行单元测试、功能测试和文档示例测试但不会运行集成测试与压力测试仓库中测试按t/unit、t/functional、t/integration、t/meticulous/、t/regression等目录组织见 t/ 目录结构tox 配置中对这几类测试的调用见 tox.ini。常用的py.test选项-x在第一个失败的测试处停止。-s不捕获输出。-v详细输出。只跑单个测试文件$ py.test t/unit/test_app.py4. 在所有支持的 Python 版本上跑测试tox仓库根目录的 tox.ini 定义了多环境测试矩阵默认环境列表包括 Python 3.8/3.7/3.6 以及 flake8、apicheck、configcheck、typecheck、docstyle、bandit、spell 等静态检查环境$ tox只想测试特定 Python 版本时用-e选项$ tox -e 2.7注以当前仓库 tox.ini 为准其envlist实际为3.8,3.7,3.6,flake8,apicheck,configcheck,typecheck,docstyle,bandit,spell且测试命令为py.test --random-order --open-files -xvv --covfaust t/unit t/functional t/integration t/meticulous/ t/regression。5. 构建文档文档依赖在 requirements/docs.txt 中$ pip install -U -r requirements/docs.txt构建文档在 docs/ 目录下执行使用 docs/Makefile$ cd docs $ rm -rf _build $ make html构建过程不应出现错误或警告成功后文档位于_build/htmlSphinx 构建实际调用见 docs/Makefile 的html目标。6. 校验你的贡献校验工具依赖在 requirements/dist.txt 中$ pip install -U -r requirements/dist.txtpyflakes 与 PEP-8$ make flakecheck该命令实际执行flake8 faust t examples见 Makefile。如果希望检查失败时不返回非零退出码使用flakes目标即make flakes其实现为带-前缀、忽略失败码的flakediag见 Makefile。API 参考完整性检查$ make apicheckapicheck通过 docs/Makefile 的 Sphinxapicheckbuilder带-W将警告视为错误验证所有模块在 API 参考中都有对应条目。内部模块应位于docs/internals/reference/公开模块应位于 docs/reference/。以公开模块faust.worker.awesome为例补全参考的步骤是以已有文件为模板cp faust.schedules.rst faust.worker.awesome.rst注意当前仓库的 docs/reference/ 中没有faust.schedules.rst实际可参考任意现有文件例如 docs/reference/faust.worker.rst在文件中把模板模块名全部替换为目标模块名然后在 index 中加入新条目最后git add并提交。配置参考完整性检查$ make configcheck该目标Makefile同样基于 Sphinxconfigcheckbuilder其 tox 环境还会额外运行 extra/tools/verify_doc_defaults.py 校验文档中的默认值与代码一致见 tox.ini。如果检查报错说明有设置项缺失需要到配置参考文档中补充说明。编码规范Coding Style虽然应该能从周围代码中自然习得风格但文档明确了几条必须遵守的约定静态类型与faust/types/接口Faust 使用静态类型并通过 mypy 校验。为了保持静态类型导入轻量、避免递归导入库中为绝大多数类定义了接口类型放在faust/types/下对于faust.App类有对应的faust.types.app.AppT对于faust.Channel有对应的faust.types.channels.ChannelT其它类同理可在 faust/types/ 目录中查看完整的接口集合例如 faust/types/app.py、faust/types/channels.py。这种设计牺牲了一些重复代码但让静态类型导入更快、减少递归导入需求。确实仍会发生递归导入时用typing.TYPE_CHECKING技巧让类型检查器导入、而运行时 Python 不导入if typing.TYPE_CHECKING: from faust.app import App as _App else: class _App: ... # noqa注意用下划线前缀命名这类占位符号提示读者使用前请三思。PEP-8所有 Python 代码必须遵循 PEP-8可以用pep8工具校验仓库层面由make flakecheckflake8负责执行。DocstringPEP-257Docstring 遵循 PEP-257推荐两种风格——多行式短描述后空一行再接细节结尾为独立空行的三引号def method(self, arg: str) - None: Short description. More details. 或单行式def method(self, arg: str) - None: Short description.而不推荐把短描述与三引号放在不同行的写法。行宽与软限制行宽不应超过 78 列软限制79 是硬限制。在 vim 中可用set textwidth78强制执行。导入顺序按Python 标准库 → 第三方包 → 当前包内其它模块分组使用 Django 的代码则是标准库 → 第三方 → Django → 当前包。每组内部按模块名排序import threading import time from collections import deque from Queue import Queue, Empty from .platforms import Pidfile from .five import zip_longest, items, range from .utils.time import maybe_timedelta禁止使用通配符导入from xxx import *。为依赖额外库的特性贡献 extras有些特性例如新的存储后端需要用户额外安装第三方库。Faust 用 setuptools 的extra_requires机制来管理这类可选依赖所有需要第三方库的新可选特性都必须走这套流程在requirements/extras下新增 requirements 文件。以 RocksDB 存储为例对应 requirements/extras/rocksdb.txt内容为纯 pip 格式当前仓库中该文件写的是python-rocksdb0.6.7。这些是 pip requirements 文件可以有版本范围约束、可以注释多个包用换行分隔# python-rocksdb 2.0 breaks Foo python-rocksdb1.0,2.0 thrift修改 setup.py。把新特性加入BUNDLES集合即文档中所说的EXTENSIONS段。当前仓库的BUNDLES定义在 setup.py包含aiodns、aiomonitor、cchardet、ckafka、ciso8601、cython、datadog、debug、fast、orjson、prometheus、redis、rocksdb、sentry、setproctitle、statsd、uvloop、eventlet、yaml等。extras_require()会遍历BUNDLES把requirements/extras/name.txt解析为对应的 extras 依赖setup.py。在 docs/includes/installation.txt 的 bundles 一节中为新特性写文档然后渲染发行版 README$ pip install -U -r requirements/dist.txt $ make readmemake readme使用sphinx2rst工具把 docs/templates/readme.txt 渲染为 README.rst见 Makefile并做 ASCII 编码校验。维护者视角发布流程Release Procedure文档后半部分是面向维护者的发布操作手册同样值得贡献者了解以便理解版本节奏。更新版本号版本号需要更新两处faust/init.py当前仓库中的版本元数据例如__version__ 1.11.0a1见 faust/init.py文档的docs/include/introduction.txt注意当前仓库实际路径为 docs/includes/introduction.txt文档原文拼写有出入。之后渲染 README 并提交、打标签$ make readme $ git commit -a -m Bumps version to X.Y.Z $ git tag vX.Y.Z $ git push --tags执行正式发布$ make distcheck # 检查 PEP-8、autodoc 索引、运行测试等 $ make dist # 注意会执行 git clean -xdf删除仓库中未跟踪的文件 $ python setup.py sdist upload --sign --identityCelery Security Team $ python setup.py bdist_wheel upload --sign --identityCelery Security Team对照 Makefile 的实现distcheck组合了lint test cleanMakefile其中lint又包含flakecheck apicheck configcheck readmecheck pep257check vultureMakefiledist为readme contrib clean-dist buildMakefileclean-dist会执行破坏性的git clean -xdfMakefile因此运行前务必确认没有未提交的本地文件。如果是新的发布系列比如首次发布 1.0 系列还需要在 Read the Docs 管理界面完成两件事进入 Edit project 把默认分支切换到该系列的分支例如 1.0 系列用1.0分支并在 versions 标签页下把上一版本也加入文档版本列表。联系人与常用通道遇到非紧急问题时优先按上文流程报告 Issue 而不是直接联系维护者。文档列出的 committer 包括 Ask Solem、Vineet Goel、Arpan ShahFaust 生态的主要包及其基础设施包括Faust包git 仓库、CI、PyPI、文档站与Mode包作为底层服务框架同样有独立仓库、CI 与文档。对内部代码结构感兴趣的贡献者可以进一步阅读 docs/developerguide/index.rst 中的开发者指南含 模块总览 与 分区分配器说明其中概述了faust.app、faust.cli、faust.streams、faust.transport、faust.types、faust.web等模块的职责以及 Worker、App、Monitor、Producer、Consumer、Agent、Conductor、TableManager、Store、Stream、Fetcher、Web 等服务在 Faust 运行时中的协作关系。赞分享流处理消息队列后端【免费下载链接】faustPython Stream Processing项目地址https://gitcode.com/gh_mirrors/fa/faust点击查看免费下载相关推荐Termshark社区贡献指南从bug报告到代码提交的完整流程Termshark社区贡献指南从bug报告到代码提交的完整流程 你是否曾在使用Termshark时遇到功能缺失或bug是否希望将自己的想法转化为代码贡献给这开发工具网络安全qpdf社区贡献指南从bug报告到代码提交的完整流程qpdf社区贡献指南从bug报告到代码提交的完整流程 想要为强大的PDF处理工具qpdf贡献代码却不知道从何开始这份终极指南将带你从bug报告到代码提交CLI开发工具CANN ops-math 算子测试报告CANN ops math 算子测试报告 团队信息 团队名称不知道叫什么名字队 所属单位广州大学 团队成员 陈慧美队长 叶翔宇成员 算子库cannCANN文档高性能计算创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考