freqtrade 贡献者实战指南从 CONTRIBUTING 规范看 PR 流程、测试与代码风格门禁【免费下载链接】freqtradeFree, open source crypto trading bot项目地址: https://gitcode.com/GitHub_Trending/fr/freqtrade本文以 CONTRIBUTING.md 为主体系统讲解向 freqtrade 提交贡献的完整流程PR 应如何发起、提交前必须通过的单元测试与 pre-commit 风格检查、CI 实际执行哪些验证以及核心维护者Committer的评审规则与晋升路径。读完后可独立完成一次符合 freqtrade 社区标准的 Pull Request 提交流程。一、贡献前必读PR 基本约定CONTRIBUTING.md 开头即给出了四条贡献约定这是所有后续流程的前提PR 必须面向develop分支而不是stable分支commit 信息、PR 描述、代码注释与变量命名一律使用英文新功能必须包含单元测试必须通过 CI建议本地先跑 pre-commit 和 pytest 提前发现问题并且应在引入 PR 中同时补充文档PR 可以标记为 draft表示工作尚未完成维护者仍会对 draft PR 及时给出反馈。对于不熟悉代码库的新贡献者文档建议优先关注带有 good first issue 标签的 issue这类 issue 通常是熟悉代码库的良好起点如果对某个功能拿不准应在提 PR 之前先通过社区渠道或 issue 讨论。从当前仓库结构看PR 模板位于 .github/PULL_REQUEST_TEMPLATE.md它要求填写 Summary并关联 issue 号、Quick changelog 和 Whats new 三部分内容并明确要求如果使用 AI 生成代码必须在 PR 描述中如实说明否则 PR 可能被直接关闭。AI 辅助贡献的三条红线文档专门设有 AI Assisted Contributions 一节对 AI 辅助开发划定了明确边界这在当前社区中是相当少见的成文规范使用 AI 生成代码时必须在 PR 描述中声明并且要自行逐行审查生成代码PR 的最终责任在作者而非 AIcommit 必须关联到你本人的人类账号而非某个通用 AI 账号绝不允许让 LLM 替你发言——所有评论、issue 和 PR 描述都必须用自己的话写体现自己的理解绝不允许让 LLM 替你思考——只提交你完全理解、并且能够解释的贡献。二、提交 PR 前第一步运行单元测试文档要求所有单元测试必须通过如果有测试失败修改你的代码让它通过——这意味着你引入了回归。仓库提供了三个粒度的 pytest 命令# 运行整个项目的测试 pytest # 只测试某一个文件 pytest tests/test_file_name.py # 只测试某一个文件中的某一个测试方法 pytest tests/test_file_name.py::test_method_name仓库内的测试脚本 tests/pytest.sh 揭示了本地与 CI 实际使用的运行方式pytest --random-order --covfreqtrade --cov-config.coveragerc tests/两个细节值得注意--random-order由 requirements-dev.txt 中固定的pytest-random-order插件提供用于消除测试间的顺序依赖覆盖率统计由 .coveragerc 控制。pyproject.toml 中的 pytest 配置还启用了asyncio_mode auto配合pytest-asyncio以及--dist loadscope的 xdist 分布策略说明测试大量涉及异步代码且按作用域分组并行执行。三、提交 PR 前第二步通过 pre-commit 风格检查文档指出我们收到大量在初步 CI 检查中失败的代码因此鼓励贡献者安装 git pre-commit 钩子在提交时立即获得反馈# 手动运行所有检查 pre-commit run -a # 安装 git hook让检查在每次 commit 时自动运行 pre-commit installpre-commit run -a会运行包括ruff、mypy、codespell在内的全部检查。当前仓库的实际钩子定义在 .pre-commit-config.yaml 中具体包含钩子作用备注extract-config-json-schema运行 build_helpers/extract_config_json_schema.py将配置 JSON Schema 与代码中的 schema 保持同步本地自定义 hook若生成了文件改动则检查失败mypyv2.3.1静态类型检查排除了build_helpers并附带 types-cachetools、types-requests、scipy-stubs 等 stub 依赖ruff ruff-formatv0.16.4代码风格检查与格式化对应文档中的Run ruff章节pre-commit-hooksend-of-file-fixer、mixed-line-ending、debug-statements、check-ast、trailing-whitespace基础卫生检查tests/、.svg、.yml、.json豁免 end-of-file-fixer.md豁免 trailing-whitespacestrip-exif移除图片 EXIF 元数据codespell拼写检查配合 pyproject.toml 中的[tool.codespell]配置豁免coo,fo,strat,zar,selectin等词zizmorGitHub Actions 工作流安全扫描保障.github/workflows不被引入恶意行为文档中的额外风格要求文档在 Additional styles applied 一节规定了自动化工具之外的人工风格约定所有 public 方法必须写 docstringdocstring 使用双引号多行 docstring 的缩进应与首个引号对齐docstring 遵循 reST 格式例如:param xxx: ...、:return: ...、:raises KeyError: ...。单独运行各检查项# ruff风格检查 格式化 ruff check . ruff format . # mypy类型检查 mypy freqtrade这些命令的判定标准直接来自 pyproject.tomlruff 的行长限制为 100启用了 mccabe复杂度上限 12、bugbear、pyflakes、pycodestyle、pyupgrade、isort、flake8-bandit 等规则集并对tests/**.py与freqtrade/freqai/**/*.py做了针对性的 per-file-ignoresmypy 侧则通过[tool.mypy]启用了 SQLAlchemy 官方插件、warn_unused_ignores并对tests.*关闭错误报告、对freqtrade.templates.*放宽attr-defined因 TA-Lib 无类型 stub。因此手动运行ruff check .与mypy freqtrade时失败项即为 pre-commit 会拦截的同一批问题。四、CI 实际执行了什么从 ci.yml 看 PR 门禁文档强调新特性必须 pass CI而 ​.github/workflows/ci.yml 展示了 PR 合并前真实经过的门禁。从 CI 配置结构看验证分为几个层次多平台矩阵测试在 Ubuntu 22.04/24.04/26.04含 ARM 运行器、macOS 14/15、Windows 2022/2025 上交叉运行 Python 3.113.14部分低版本组合被 exclude直接印证了文档中跨平台兼容性Windows、Mac Linux这一维护者职责依赖安装与版本对齐uv pip install -r requirements-dev.txt后先运行 build_helpers/freqtrade_client_version_align.py 校验主包与 ft_client/ 客户端版本一致单元测试绝大多数矩阵项执行pytest --random-order --durations 20 -n auto并行 随机顺序其中 Ubuntu 24.04 Python 3.14 一项额外带--covfreqtrade --covfreqtrade_client --cov-config.coveragerc上传覆盖率生成物一致性检查CI 会运行python build_helpers/extract_config_json_schema.py和python build_helpers/create_command_partials.py随后执行git status --porcelain检查仓库是否变脏——这意味着修改配置 schema 或 CLI 命令后必须同步提交重新生成的 build_helpers/schema.json 等产物否则 CI 直接失败功能冒烟CI 末尾还会用freqtrade create-userdir、freqtrade new-strategy含 minimal/advanced 模板生成策略并对 tests/testdata 中的测试数据执行真实的多策略 backtesting 与 hyperopt确保核心命令链路未被破坏。五、核心维护者指南Committer 的职责与晋升CONTRIBUTING.md 后半部分是一份完整的 (Core)-Committer Guide对社区治理同样有参考价值。PR 处理优先级维护者按以下顺序从高到低处理 PR修复失败的测试在任何受支持平台或 Python 版本上失败都算 broken补充覆盖边角场景的额外测试文档的小修Bug 修复文档的大改新功能。同时要求每个 PR 都必须满足 Contributing 文档中的全部要求并且保持功能 PR 尽可能小——一个 PR 最好只引入一个新功能。Issue 处理流程需要紧急修复的 bug 应标记进下一个 patch release然后要么自己修复要么标记为 please-help对其他 issue 则鼓励友好讨论、缓和争论、公开发表观点。自我代码变更的强制互审所有代码变更——无论作者是谁——都必须由其他人评审并合并这条规则同样适用于全体核心维护者。例外只有三种对他人提交的 PR 做小幅修正正式发版期间release manager 可做出必要的变更强化既有主题的小幅文档修改最常见的是拼写与语法。维护者职责清单保证每个被接受的变更在 Windows、Mac、Linux 三个平台上都兼容确保没有恶意代码进入核心代码对任何重大变更先建 issue公开讨论并获取社区反馈功能 PR 保持最小化一个 PR 一个功能对新手保持欢迎态度鼓励来自不同背景的新贡献者加入。如何成为 Committer贡献者获得 commit 权限的偏好条件依次为有 freqtrade 及相关开源项目的过往贡献记录——既包括代码已接受和评审中的都算也包括在 issue tracker 和 PR 评审中的友好参与数量与质量均被考量代码风格简洁、最小化、干净得到其他核心维护者认可具备跨平台开发与测试的资源条件有持续投入项目的时间。文档还特别说明了安全设计成为 Committer 并不会自动获得develop或stable的写权限——因为用户把交易所 API key 托付给了 Freqtrade直接推送到主干的风险过高成为 Committer 一段时间并继续表现良好后才可能被提升为 Core Committer 并获得完整仓库权限。六、本地开发环境搭建速查结合文档指引与仓库文件本地贡献环境的搭建路径如下仓库为只读参考以下命令在你的克隆副本中执行Python 版本setup.sh 声明受支持版本为 3.113.14与 pyproject.toml 的requires-python 3.11及 CI 矩阵一致若检测到uv会优先用它加速安装依赖安装运行./setup.sh并在提示中选择安装开发依赖等价于pip install -r requirements-dev.txt——该文件在 requirements.txt 之外叠加了 plot、hyperopt、freqai、freqai_rl 与文档依赖并固定了 ruff、mypy、pre-commit、pytest 全家桶pytest-asyncio、pytest-cov、pytest-mock、pytest-random-order、pytest-timeout、pytest-xdist、time-machinedatetime mock等版本启用自动检查pre-commit install后每次git commit自动触发第三节列出的全部钩子验证闭环pytest tests/test_xxx.py::test_yyy定位回归→pre-commit run -a消除风格问题→ 按 PR 模板 填写 Summary/Changelog/AI 声明向develop分支发起 PR。至此从阅读 CONTRIBUTING.md 的约定到本地通过 pytest 与 pre-commit再到 CI 矩阵、生成物一致性与功能冒烟的逐层门禁最后到维护者的评审与互审规则构成了一条完整的 freqtrade 贡献闭环。【免费下载链接】freqtradeFree, open source crypto trading bot项目地址: https://gitcode.com/GitHub_Trending/fr/freqtrade创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考