FastF1 贡献指南全解析：从提交 Bug 到合入 Pull Request 的开发协作规范

FastF1 贡献指南全解析从提交 Bug 到合入 Pull Request 的开发协作规范【免费下载链接】Fast-F1FastF1 is a python package for accessing and analyzing Formula 1 results, schedules, timing data and telemetry项目地址: https://gitcode.com/GitHub_Trending/fa/Fast-F1FastF1fastf1是用于访问与分析 F1 赛果、赛历、计时数据与遥测数据的 Python 包其官方贡献指南docs/contributing/contributing.rst定义了社区参与项目的完整路径从报告 Bug、请求新功能到通过 Fork-Pull Request 流程贡献代码与文档再到 API 演进、日志系统与优雅降级等编码规范。读完本文你将掌握一套可直接落地执行的贡献流程——知道如何写出一份高质量 Bug 报告、如何搭建开发环境并跑通测试、如何按弃用流程演进公开 API以及如何在数据加载失败时用soft_exceptions实现加载不完整数据优于完全不加载的容错设计。贡献概览社区参与的四条路径FastF1 的贡献指南开篇即强调社区正在逐步成长欢迎任何人参与贡献且并非所有贡献都需要写代码。围绕 docs/contributing/index.rst 的归纳贡献方式主要包括报告 Bug提交 issue请求新功能提交 feature request为文档纠错、澄清 docstring、补充示例直接提交代码修复或新特性Pull Request提问与澄清文档中不清楚的地方。指南还特别要求在做出任何贡献之前务必先阅读 AI 政策ai-policy锚点。该政策禁止提交完全由 AI 生成的 Pull Request要求贡献者能够理解自己提交的代码、以本人语言沟通、披露 AI 工具的使用情况并对版权负责——维护者有权关闭违反政策的 issue 或 PR甚至封禁反复违规的账号。报告 Bug一份高质量 Bug Report 的四个要素如果发现代码或文档中的 Bug指南建议直接在 GitHub 的 issue 区提交新 issue也可以在其中提交功能请求或 Pull Request。对于不太确定是否由 Bug 引起的一般性问题应改到 Discussions 中讨论。报告 Bug 时请尽量包含以下内容issue 创建页面已预置了 Markdown 模板协助组织信息简短的总览摘要通常 12 句话说明问题本质可复现的最小代码片段自包含、可复制粘贴即可运行并尽可能缩减到最小必要规模实际输出运行该代码片段得到的结果预期输出你期望得到的结果FastF1 版本与 Python 版本可通过以下命令获取 import fastf1 fastf1.__version__ # doctest: SKIP 3.9.0 import platform platform.python_version() # doctest: SKIP 3.12.5注意原文档示例中的版本号如2.2.1仅为占位示例实际输出以你本地安装的版本为准。当前仓库正处于 v3.9.0 开发阶段见 docs/changelog/current.rst而 pyproject.toml 要求Python 3.10因此示例中的 Python 3.9.x 也不再是受支持的运行环境。请求新功能鼓励提出 参与实现功能请求同样通过 GitHub issue 区提交。由于 FastF1 是资源有限的开源项目指南明确鼓励请求者在能力范围内参与到实现中而不仅仅是指出需求——这既加快了功能落地也符合项目资源有限、人人贡献的社区定位。贡献代码标准的 Fork Pull Request 工作流贡献代码的首选方式是对主仓库做 Fork然后提交 Pull RequestPR。指南给出了完整的六步流程若尚无 GitHub 账号先注册一个Fork 项目仓库点击页面顶部的 Fork 按钮在你自己账号下生成一份代码副本克隆到本地git clone https://github.com/YOUR GITHUB USERNAME/Fast-F1.git进入目录并安装本地开发版 FastF1详见下文搭建开发环境一节对应 devenv_setup.rst 中的installing_for_devs锚点创建特性分支并开始修改git checkout -b my-feature origin/main指南强调永远不要在main分支上直接开发在本地用 Git 做版本管理编辑完例如fastf1/core.py后提交并推送git add fastf1/core.py git commit git push -u origin my-feature最后回到你 Fork 后的仓库网页点击 Pull request 将改动发送给维护者审查。提交 Pull Request 前的检查清单coding_guide.rstpr-guidelines锚点为 PR 作者总结了核心注意事项contributing.rst 的 Contributing pull requests 一节则列出了提交前的硬性检查项关联 issue若 PR 解决了某个 issue请在标题中描述问题并在 PR 描述中提及 issue 编号以便建立链接Docstring所有公开方法应有信息量充足的 docstring必要时附示例用法采用 Google docstring 规范由 Sphinx Napoleon 扩展解析FastF1 文档特意说明其与 Matplotlib 的 numpydoc 风格不同见 documenting_fastf1.rst代码风格遵循 PEP8由 ruff 强制检查所有改动行的最大行长为79 字符。命令行检查方式python -m pip install ruff ruff check .注意上述ruff check .不会标记过长的行行长规则需由编辑器插件或专门的格式化检查触发若安装了 pre-commit 钩子ruff 会在每次提交前自动运行见下文pre-commit 钩子测试覆盖无论是新功能还是 Bug 修复都应具备良好的测试覆盖详见 testing.rst导入约定统一采用标准 SciPy 生态导入方式import numpy as np import pandas as pd import matplotlib as mpl import matplotlib.pyplot as plt更新 Changelog若属于重要新特性需在 Changelog 部分添加条目。当前仓库中该部分位于 docs/changelog/index.rst目录下按版本拆分为current.rst、previous.rst与各v*.rst文件原文档所述的docs/changelog.rst单文件结构已被拆分历史整洁更新 PR 时应尽量改写已有提交而非追加修复提交git commit --amend --no-edit git push [your-remote-repo] [your-branch] --force-with-leasePR 可以以 draft草稿状态提前打开以获取维护者反馈审查者响应速度有限若数日无反馈可在 PR 下留言催促。此外要注意FastF1 的 ruff 配置pyproject.toml排除了scripts、fastf1/tests、fastf1/testing、fastf1/legacy.py等路径并启用了B/E/F/ISC/W/UP/...等多组 lint 规则fastf1/_api.py单独豁免了E501行长规则。贡献文档与示例画廊文档源码与代码位于同一仓库同样通过 PR 流程合入。作为 FastF1 的终端用户你往往比核心开发者更清楚文档哪里可以改进可做的贡献包括修正拼写错误typo澄清某个 docstring编写或更新一个示例图example plot。为示例画廊贡献脚本FastF1 使用 Sphinx-Gallery 生成示例画廊画廊内容由 examples 目录下的文件生成内部按general、lap_times、results_strategy、standings、telemetry等主题分子目录每个子目录含GALLERY_HEADER.rst与若干plot_*.py脚本。要新增画廊示例只需在该目录新建一个包含全部绘图代码的 Python 文件并按 Sphinx-Gallery 的格式约定组织标题、分节与解释性文本。子目录内现有如 plot_speed_trace_comparison.py、plot_strategy.py 等脚本可供参考。这些示例同时会被测试框架执行pytest.ini将examples纳入testpaths并配合--mpl与 fastf1/tests/mpl-baseline 基线图做绘图回归校验见 test_example_plots.py。编码指南版本策略、API 演进与日志规范受支持的 Python 与依赖版本项目承诺支持的版本范围基于 NEP 29 建议制定Python支持项目发布前 42 个月内发布的所有次要版本且至少支持最新的两个次要版本当前 pyproject.toml 实际要求requires-python 3.10Numpy / Pandas / Matplotlib支持发布前 24 个月内发布的所有次要版本且至少支持最新三个次要版本其他依赖尽量支持计划发布日前 12 个月内首次发布的所有次要版本或支持最低 Python 所需的最老版本只有在新特性必需或旧版本与其他最低版本要求不兼容时才会提升依赖下限。这些约束与 pyproject.toml 中的实际依赖声明如matplotlib3.8.0,4.0.0、numpy1.26.0,3.0.0、pandas2.1.1,3.0.0相互印证上界防止未来大版本破坏兼容性下界则对应最低支持范围。API 变更与弃用流程两阶段警告再移除API 的一致性与稳定性对 FastF1 极其宝贵因此任何签名、行为或移除类变更都必须遵循如下弃用流程除非开发者认为存在极罕见的例外基本规则弃用目标定在下一个次要版本如 3.x被弃用的 API 一般在弃用引入后的两个次要版本后移除核心开发者可按个案延长过渡期弃用期间旧 API 必须保持完全可用若存在替代 API则替代品也应在弃用期内可用。引入弃用在 Changelogdocs/changelog/index.rst记得引用对应 PR中公告弃用尽可能在调用被弃用 API 时发出警告且警告级别有严格要求弃用公告发布的第一个次要版本使用DeprecationWarning——默认大多不展示给终端用户但开发者可见从第二个次要版本起改用FutureWarning——终端用户与开发者都会看到。仓库中有大量实例可印证该流程例如 docs/changelog/current.rst 记载fastf1.utils.recursive_dict_get、to_datetime、to_timedelta被弃用实现已移至fastf1.internals.parsing_helpers公开名称继续转发但发出DeprecationWarning以及fastf1.utils.delta_time在 v3.0.0 弃用后于 v3.9.0 被正式移除。到期移除再次在 Changelog 中公告内容通常可复制原弃用通知并稍作调整修改代码功能并删除相关弃用警告。另外由于 FastF1 经常需要适配外部 API如上游数据接口的无预警变化必要时允许在比上述流程更短的时间内做变更但总原则是尽可能避免破坏性变更并给用户充分的预警与适应时间。新增公开 API 的注意事项任何未以下划线开头的新函数、参数与属性都会成为 FastF1 公开 API 的一部分而修改既有 API 代价高昂因此新增 API 时要格外谨慎辅助函数与内部属性务必用下划线前缀标记为私有仔细斟酌函数与变量命名尽量沿用现有 FastF1 API 的模式与命名约定尽可能将参数设计为keyword-only仅关键字参数为未来以兼容方式增加参数留出余地。新增模块与文件的打包配置如果新增或重组了文件与目录需确保新文件被纳入打包匹配模式。原文档此处指向setup.cfg的packages配置以当前仓库实际为准打包配置位于 pyproject.toml 的[tool.hatch.build.targets.wheel]/[tool.hatch.build.targets.sdist]段include包含fastf1/**、requirements/**、examples/**并排除fastf1/tests/**与fastf1/testing/**。新增模块时需确认其被这些 include 模式覆盖。使用日志系统替代 print 调试FastF1 基于标准库logging构建了一套分层日志系统创建一个主 loggerfastf1各子模块使用其子 logger。指南明确要求在所有想写print做调试的地方改用logger.debug。在模块顶部引入from fastf1.logger import get_logger # 每个模块只设置一次 logger get_logger(__name__) # 使用 logger.info(Here is some information) logger.debug(Here is some more detailed information)这会写入名为fastf1.yourmodulename的 logger。从源码看fastf1/logger.pyget_logger本质上是LoggingManager.get_child它为fastf1根 logger 创建子 logger根 logger 级别为DEBUG控制台 handler 默认级别为INFO输出格式为{module: 8} {levelname: 10} \t{message}。默认情况下FastF1 向sys.stderr输出所有高于INFO级别的日志消息用户可通过 fastf1.set_log_level如fastf1.set_log_level(WARNING)统一调整可用级别按严重性递增为DEBUG、INFO、WARNING、ERROR、CRITICAL。五个日志级别的使用准则logger.critical与logger.error仅用于会使库无法继续使用但不会杀掉解释器的错误logger.warning向用户告警例如某操作已优雅失败、某动作可能产生非预期副作用等logger.info用户可能在程序行为异常时需要的信息。例如某位车手未参加某场 session导致该车手部分数据无法加载但其余车手数据仍可正常使用logger.debug最不常显示、因而可以最啰嗦仅用于 FastF1 开发与调试所需的信息。允许可选功能优雅失败soft_exceptions装饰器FastF1 处理大量可能意外变化、含未知值或并非始终可用的数据。理想做法是让代码尽可能健壮但有些场景无法完全预见异常数据例如加载可选数据天气数据、遥测等对数据进行附加交叉验证为提高数据精度而应用修正。此时若任务失败FastF1 应向用户发出警告但不应崩溃——尤其是在数据加载阶段加载不完整数据永远优于完全不加载。为此fastf1.logger提供了soft_exceptions装饰器from fastf1.logger import soft_exceptions soft_exceptions(descr_nameoptional data processing, msgFailed to do some optional data processing, loggerlogger) def _optional_data_loading(): ... return其源码实现fastf1/logger.py展示了三个关键行为在函数调用外包一层大的try: ... except Exception: ...失败时以WARNING级别向用户展示msg完整 traceback 以DEBUG级别记录并冠以Traceback for failure in {descr_name}前缀必须传入当前模块的logger作为第三个参数。值得注意的两个实现细节FastF1CriticalError来自 fastf1/exceptions.py会被无条件重新抛出——这类错误属于必须终止的范畴不参与优雅降级由于兜底捕获会让调试器无法停在未处理异常上开发时可关闭该机制。关闭方式有两种将LoggingManager.debug显式设为True或设置环境变量FASTF1_DEBUG1fastf1/logger.py 会在启动时读取该变量并发出UserWarning。关闭后所有被装饰函数的异常将直接向上抛出。搭建开发环境与安装 pre-commit 钩子详见 devenv_setup.rstinstalling_for_devs锚点核心步骤为创建专用虚拟环境venv也可用 condapython -m venv file folder location source file folder location/bin/activate # Linux/macOS file folder location\Scripts\activate.bat # Windows cmd.exe file folder location\Scripts\Activate.ps1 # Windows PowerShell克隆仓库有权限时可用git走 SSH便于二步验证git clone https://github.com/theOehrly/Fast-F1.git可编辑模式安装python -m pip install -e .editable 模式会在环境中放置指向开发源码目录的链接改动后无需重新安装即可导入最新代码。安装开发与测试依赖python -m pip install -r requirements/dev.txt如需构建文档再安装python -m pip install -r requirements/doc-build.txtrequirements/dev.txt 实际包含pytest、pytest-mpl、ruff、isort、pre-commit、requests-mock、xdoctest、websockets等。安装 pre-commit 钩子推荐钩子定义在顶层.pre-commit-config.yaml会在每次git commit时自动检查并部分自动修复ruff 与 isort 风格问题pip install pre-commit pre-commit install测试、代码风格与 CI运行测试FastF1 使用 pytest测试位于 fastf1/tests 目录测试基础设施定制在fastf1.testing。先完成开发环境搭建然后在仓库根目录运行python -m pytest首次运行前需手动创建test_cache/缓存目录。常用 pytest 参数参数作用-v/--verbose更详细的输出-n NUM在 NUM 个进程上并行运行需 pytest-xdist--captureno/-s不捕获 stdout运行单个测试可提供文件路径函数名用双冒号分隔pytest fastf1/tests/test_events.py::test_event_get_session_date测试无需安装但 FastF1 本体应已安装。仓库的 pytest.ini 将fastf1、docs、examples全部纳入测试路径并启用了 doctest--doctest-glob*.rst、--xdoctest与--mpl绘图基线对比同时把大部分警告升级为错误以确保代码库干净。代码风格检查FastF1 使用 ruff 与 isort 保证风格一致、可读全部代码应符合 PEP8ruff check . python -m isort .若安装了 pre-commit 钩子这两条命令会在每次提交前自动执行。GitHub Actions CI 与定向跳过每次推送到仓库或更新 PR 时GitHub Actions 都会在受支持的 Python 版本上运行全部测试。个别罕见场景下可在提交信息中加入特定注释跳过某些测试[skip-pytest]跳过所有 Python 版本上的 pytest[skip-ruff]跳过 ruff 风格检查[skip-isort]跳过 isort 导入顺序检查[skip-doc-build]跳过文档构建[skip-readme-test]跳过面向 PyPI 的 README 渲染测试构建文档文档由 Sphinx 从 docs/ 下的 reStructuredText.rst源码生成配置入口为 docs/conf.py。在docs/目录下执行make html首次构建前需在项目根目录手动创建doc_cache/缓存目录。构建产物位于docs/_build/html可用浏览器直接打开 html 文件查看make show文档编写风格整体沿用 Matplotlib 的文档规范唯一显著例外是 docstring 使用Google 格式而非 numpydoc 格式。常见误区与快速自查在main分支上直接开发永远先git checkout -b创建特性分支报告 Bug 缺版本信息务必附上fastf1.__version__与platform.python_version()缺少版本将大幅增加维护者复现成本破坏既有 API 而不走弃用流程先公告到 Changelog第一版用DeprecationWarning第二版起用FutureWarning两个次要版本后再移除用print调试统一改为get_logger(__name__)后的logger.debug新增公开 API 未加下划线任何非下划线开头的名字都会进入公开 API命名与签名设计需格外慎重数据加载可选步骤直接抛异常优先用soft_exceptions包装让单个数据源的失败不至于拖垮整个 session忘记更新打包配置新增文件后确认被 pyproject.toml 的 hatch include 模式覆盖提交前不跑测试与 lintPR 会被 CI 自动检查提前本地执行python -m pytest、ruff check .、python -m isort .可显著加快合入速度。遵循上述流程与规范你既可以为 FastF1 提交一份被维护者认真对待的 Bug 报告也能将代码、文档或示例画廊的改进平滑地合入主仓库成为 F1 数据分析生态的贡献者之一。【免费下载链接】Fast-F1FastF1 is a python package for accessing and analyzing Formula 1 results, schedules, timing data and telemetry项目地址: https://gitcode.com/GitHub_Trending/fa/Fast-F1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考