sktime 贡献指南从首次提交到成为核心贡献者的完整参与路径【免费下载链接】sktimeA unified framework for machine learning with time series项目地址: https://gitcode.com/GitHub_Trending/sk/sktime导读sktime 是一个面向时间序列机器学习的统一框架涵盖预测、时序分类、聚类、回归、参数估计、异常检测等丰富的学习任务。本文以官方贡献指南为核心系统梳理从「在 Discord 打声招呼」到「第一个 PR 被合并」再到「持续贡献、参与评审、提交增强提案STEP」的完整参与路径并结合仓库源码说明开发环境搭建、扩展模板、check_estimator一致性测试、pytest测试框架与编码规范等关键细节。读完本文你将掌握为 sktime 提交代码、报告缺陷、评审他人 PR 以及设计重大改进的标准流程与实操命令。一、sktime 欢迎怎样的贡献sktime 的贡献指南docs/source/get_involved/contributing.rst开门见山地强调一句话We value all kinds of contributions - not just code.我们重视所有类型的贡献而不仅仅是代码。这意味着即使你不擅长写代码也可以通过以下方式参与参与社区讨论、答疑与协作编码改进文档与 docstring报告 bug、提出功能需求评审他人的 Pull Request编写并提交增强提案STEP。项目尤其鼓励新贡献者参与并且把帮助新人学习成长视为重要目标——官方 Discord 上有专门的#intro频道用于新人报到与答疑社区还会定期举办协作编程会议collab sessions与专题 stand-up 和 tech sessions。二、官方推荐的新手五步路径contributing.rst 给出了面向首次贡献者的推荐步骤在 Discord 的#intro频道打声招呼让社区认识你遇到问题也更容易获得帮助。完成开发环境搭建参见 developer guide 中的安装说明详见下文三、搭建开发环境。挑选一个合适的 first issue从项目标记了good first issue的 issue 列表中挑选一个小而简单的任务先跑通整套贡献流程。参加社区活动可以参加定期的社区协作会话community collab sessions或某个主题的 stand-up 与 tech sessions。在第一个 PR 合并后持续贡献可继续参加周五社区协作会话也可以选择申请 mentoring导师制项目获得更系统的指导。建议第一步选任务时刻意挑内容简单、改动范围小的 issue目的是先学会流程fork → 分支 → PR → 评审 → 合并而不是一上来就挑战大功能。三、搭建开发环境3.1 支持范围与安装类型根据 docs/source/installation.rst当前仓库支持的运行环境为Python 版本3.10、3.11、3.12、3.13、3.14操作系统macOS、类 Unix 系统、Windows 8.1 及以上。安装方式按使用场景分为三类稳定版生产环境、最新不稳定开发版预发布测试、完整开发者环境贡献者与第三方扩展开发者。本文聚焦最后一种。3.2 完整开发者环境contributors / extension developers 专用标准流程如下官方推荐使用 condavenv或其他虚拟环境管理器流程类似# 1. 先在 GitHub 上 fork 仓库并克隆到本地详见第四节 git clone gitgithub.com:username/sktime.git cd sktime # 2. 创建并激活虚拟环境以 conda 为例 conda create -n sktime-dev python3.11 conda activate sktime-dev # 3. 可编辑安装 开发依赖 pip install -e .[dev] # 4. 如需软依赖soft dependencies可选全量安装 pip install -e .[all_extras,dev]安装成功后会看到 successfully installed sktime 提示。仓库的依赖声明集中在 pyproject.toml其中dev依赖组已包含后续要用到的pre-commit等工具。注意all_extras只为了让全部估计器可用或运行全部测试会显著拖慢下载与测试速度普通场景建议只装核心依赖、按需补装软依赖。部分软依赖在 mac ARMM1/M2 等处理器上可能无法安装属已知问题详见安装文档的 Troubleshooting 部分。3.3 常见问题速查Module not found最常见原因是仅安装了最小依赖而所用估计器需要某个未安装的软依赖包。解决方式是补装该包或改用sktime[all_extras]全量安装。ImportError多为虚拟环境链接异常请确认环境已激活并与 IDE含 Jupyter kernel正确关联。四、Git 与 GitHub 工作流完整流程见 docs/source/developer_guide/git_workflow.rst分为一次性初始化和每次开发新功能两个部分。4.1 一次性初始化fork 并克隆仓库# 1. 在 GitHub 上点击 Fork创建你自己的副本 # 2. 克隆你的 fork 到本地 git clone gitgithub.com:username/sktime.git cd sktime # 3. 配置 upstream 远程仓库指向官方仓库 git remote add upstream https://github.com/sktime/sktime.git # 4. 验证远程配置 git remote -v # origin https://github.com/username/sktime.git (fetch/push) # upstream https://github.com/sktime/sktime.git (fetch/push)其中 Fork 操作每个 GitHub 账号只需做一次clone与upstream配置每台新机器做一次系统重装后需重做。4.2 每次开发新功能标准循环# 1. 同步 main 分支与上游 git fetch upstream git checkout main git merge upstream/main # 2. 从最新的 main 创建功能分支绝不直接在 main 上开发 git checkout -b feature-branch # 3. 开发、暂存并提交 git add modified_files git commit # 4. 推送并创建 Pull RequestWIP 阶段可先开 draft PR git push --set-upstream origin feature-branch两个值得强调的社区约定合并期间同步 mainPR 评审期间官方 main 可能持续更新用git merge而非git rebase更新你的功能分支。sktime 在 main 上会把所有 PR squash 成单个提交因此你的分支历史并不重要rebase会重写历史、可能造成难以恢复的状态官方强烈反对使用。PR 越早开越好哪怕功能未完成也建议尽早开 draft PR让社区尽早知晓你的工作并给出反馈。4.3 进阶并行分支与 PR 堆叠多任务并行每个独立任务各建一个分支严禁在同一个分支上混合多个任务否则历史混乱、评审困难、冲突风险大幅上升。PR 堆叠stacking当任务 A 是任务 B 的前置如先修 bug 再做估计器可以在 A 的分支上再开 B 的分支并各自提交 PR在 PR 描述中注明依赖关系。维护链上所有分支同步的通用做法是更新 fork → 依次把main合并进 A、把 A 合并进 B、把 B 合并进 C……逐级解决冲突。清理PR 合并后可执行git branch -D feature-branch删除本地分支用git push origin --delete feature-branch删除远端分支。五、编码规范与本地代码质量检查5.1 遵循的标准根据 docs/source/developer_guide/coding_standards.rst遵循PEP8编码指南使用ruff做代码格式化与 lintmax_line_length88其余配置见仓库根目录 pyproject.toml使用numpydoc强制 NumPy docstring 标准并叠加 sktime 特有的文档约定。5.2 sktime 特有命名与编码约定非类名用下划线分词n_instances而非ninstances例外地允许X、Y、Z及其派生名如X_train作为变量名——这是沿用 scikit-learn 生态的习惯避免一行多条语句控制流if/for后换行仓库内部引用使用绝对导入源码中禁止import *——它让符号来源不明确且会阻断 pyflakes 等静态分析工具发现 bug。5.3 用 pre-commit 自动检查pip install -e .[dev] # 确保含 dev 依赖 pre-commit install安装后每次git commit都会自动对所有改动文件运行全部代码质量检查。如需临时豁免某一行可在行尾追加# noqa: rule注释规则名参见 ruff 规则表。5.4 IDE 集成在 VS Code 中安装 ruff 扩展后它会自动读取项目pyproject.toml/ruff.toml/.ruff.toml中的配置建议同时在settings.json中加入editor.ruler: 88显示最大行长。注意 ruff 等工具需要安装到 IDE 所用的 Python 环境里通过[dev]依赖安装即可。六、实现与提交一个估计器sktime 贡献的重头戏通常是为某个 scitype学习任务类型如 forecaster、time series classifier实现新估计器详见 docs/source/developer_guide/add_estimators.rst。6.1 高层次的五步流程确定估计器的类型forecaster、classifier 等 scitype把对应类型的扩展模板extension template复制到目标位置按模板补全实现运行测试套件或check_estimator工具做接口一致性验证若测试暴露问题修复后回到第 4 步。6.2 扩展模板与双接口设计仓库的 extension_templates/ 目录为每种 scitype 提供了填空式模板包括forecasting.py、classification.py、transformer.py、clustering.py、distance_based、alignment.py、detection.py、param_est.py、split.py等。模板背后的设计是双接口模式公开接口public interface由各 scitype 的基类定义如BaseForecaster定义fit/predict遵循策略strategy模式。具体估计器永远不重写fit、predict等公开方法扩展接口extender interface模板中要求实现的是私有内层方法如_fit、_predict遵循模板template模式。样板逻辑输入检查、类型转换、自动向量化等全部沉淀在公开方法中避免像 scikit-learn 那样在每个估计器里重复check_X之类的样板。这与 scikit-learn 的扩展方式有本质区别sktime 禁止覆盖公开方法实现只发生在私有内层方法从而复用更丰富的样板逻辑如自动向量化、输入格式转换。6.3 模板中的典型 todo使用模板就是搜索todo并按提示逐项完成典型项包括确定估计器的名字与参数填充__init__把参数写入self并调用super().__init__()填写模块与类的 docstring建议在参数敲定后尽早写可当作实现规格设置估计器的tags一部分 tag 是能力声明如是否支持 nan另一部分决定内层方法看到的输入格式如X_inner_mtype。若内层实现假定numpy.ndarray或pandas.DataFrame通过 tag 声明可免去转换样板。mtype 字符串可在datatypes.MTYPE_REGISTER中找到见 sktime/datatypes/_registry.py数据类型约定的教程见 examples/AA_datatypes_and_datasets.ipynb。例如把y_inner_mtype设为pd.DataFrame就能保证_fit收到的y一定是符合 sktime 容器规范的 DataFrame实现内层方法_fit/_predict等其输入保证比公开方法更强由已设置的 tag 决定在get_test_params中填充测试参数尽量覆盖估计器内部的主要分支以提升测试覆盖。6.4 常见注意事项模板中同样有说明__init__参数写入self后不得再修改参数为估计器对象组件时一般要用sklearn.clone克隆后只在克隆体上调用方法方法应避免对入参产生副作用非状态改变的方法一般不应写self通常无需自己实现get_params/set_params——sktime的BaseEstimator继承自 scikit-learn自带实现只有异构复合结构如含嵌套估计器的 pipeline等复杂场景才需要自定义。6.5 用check_estimator验证接口一致性最快捷的验证方式是 sktime/utils/estimator_checks.py 提供的check_estimatorfrom sktime.utils.estimator_checks import check_estimator from sktime.forecasting.naive import NaiveForecaster check_estimator(NaiveForecaster)默认返回一个以测试名 fixture 组合字符串为键的dict如test_repr[NaiveForecaster-2]值要么是PASSED要么是失败时抛出的异常对象——默认不抛异常想直接抛异常便于调试传raise_exceptionsTrue只抛执行顺序中遇到的第一个异常用tests_to_run/tests_to_exclude筛选或排除测试参数为测试名不含方括号部分例如check_estimator(NaiveForecaster, tests_to_runtest_constructor) # {test_constructor[NaiveForecaster]: PASSED}用fixtures_to_run/fixtures_to_exclude筛选或排除具体 test-fixture 组合合法字符串正是默认调用返回的 dict 键例如check_estimator(NaiveForecaster, fixtures_to_runtest_repr[NaiveForecaster-2]) # {test_repr[NaiveForecaster-2]: PASSED}推荐的调试工作流① 全量运行找出失败项 → ② 用fixtures_to_run/tests_to_run收窄范围 → ③ 仍不明朗就加raise_exceptionsTrue看 traceback → ④ 还不行就在check_estimator那行代码上挂调试器。6.6 在仓库克隆中跑测试套件若估计器落在 sktime 仓库内部可直接运行基于pytest的测试套件CI/CD 同样基于 pytest。从命令行只测某个估计器pytest -k EstimatorName这与check_estimator(EstimatorName)的效果基本一致。通用接口一致性测试集中在TestAllEstimators、TestAllForecasters等类中包级测试在 sktime/tests/test_all_estimators.py模块级如 sktime/forecasting/tests/test_all_forecasters.py。pytest 生成的 test-fixture 字符串总包含估计器名作为子串与check_estimator返回的键一致因此也可以直接在代码库中按def test_xxx前缀搜索这些测试串来定位相关测试源码。6.7 第三方扩展包中的测试第三方扩展包开源或闭源可通过三种方式复用 sktime 的接口一致性测试直接导入check_estimator它可以在unittest、pytest等任意测试框架中运行导入parametrize_with_checks同样位于sktime.utils.estimator_checks在 pytest 套件中把一组估计器类/实例参数化到独立测试用例from sktime.utils.estimator_checks import parametrize_with_checks parametrize_with_checks(OBJS_TO_TEST) def test_sktime_api_compliance(obj, test_name): check_estimator(obj, tests_to_runtest_name, raise_exceptionsTrue)直接继承测试类如test_all_estimators.TestAllEstimators、test_all_forecasters.TestAllForecasterspytest 会自动发现。6.8 把估计器并入 sktime 本体时的额外要求满足文档规范docs/source/developer_guide/documentation.rst在 docs/source/api_reference 下对应的.rst文件中登记到 API 参考作者应把自己加入估计器的authors和maintainerstag若依赖/新增软依赖需遵循 docs/source/developer_guide/dependencies.rst 中的步骤保证估计器在目标位置通过完整本地测试pytest -k EstimatorNameget_test_params的测试参数应控制在秒级运行时长以适配远程 CI/CD。依赖 Cython 的估计器有专门流程C 代码放在独立的sktime-cython包中不得直接进入 sktimesktime 内只放继承自 base class 的接口层并设置python_dependenciessktime-cython与tests:vmTrue。第三方 Cython 估计器则建议代码放在自有包home-package中sktime 内通过转发接口如_placeholder_record模板或 delegator 模式接入。七、测试框架一览sktime 用pytest做估计器接口合规与代码正确性测试框架说明见 docs/source/developer_guide/testing_framework.rst。7.1 三层测试架构测试与估计器的继承层次大致对应分三层包级package level校验BaseObject/BaseEstimator规范合规位于 sktime/tests/test_all_estimators.py模块级module level校验具体估计器与其 scitype 基类的一致性如 sktime/forecasting/tests/test_all_forecasters.py、distances/tests/test_all_dist_kernels.py等低层low level在tests文件夹中按文件测试单个功能。约定每个模块含tests目录tests目录可含_config.py收集模块级测试配置通用测试工具位于sktime.utils._testing。7.2 核心机制fixture 参数化与场景scenariosktime 通过向pytest_generate_tests注册的插件自动为 fixture 生成参数化循环开发者写测试时无需手写循环。典型的接口测试长这样def test_fit_returns_self(object_instance, scenario): Check that fit returns self. fit_return scenario.run(object_instance, method_sequence[fit]) assert ( fit_return is object_instance ), fEstimator: {object_instance} does not return self when calling fitobject_instance由create_test_instances_and_names根据各估计器get_test_params构造的全部测试实例scenario封装数据输入与调用序列的对象scenario.run等价于按scenario_kwargs调用fit(**kwargs)等。sktime 的pytest_generate_tests只把对当前估计器适用的 scenario 传给测试。场景定义示例来自utils/_testing/scenarios_forecastingclass ForecasterFitPredictUnivariateNoXLateFh(ForecasterTestScenario): Fit/predict only, univariate y, no X, no fh in predict. _tags {univariate_y: True, fh_passed_in_fit: False} args { fit: {y: _make_series(n_timepoints20, random_stateRAND_SEED)}, predict: {fh: 1}, } default_method_sequence [fit, predict]scenario.run(object_instance)会先fit(y...)再predict(fh1)并返回结果。场景还有is_applicable(estimator)判断是否适用如单变量场景对多元 forecaster 不适用并且场景继承BaseObject因此复用 sktime 的 tag 系统。7.3 远程 CI 的矩阵分配策略远程 CI 在所有受支持 OS × Python 版本组合上运行三层测试但通过subsample_by_version_os位于tests.test_all_estimators由BaseFixtureGenerator的pytest_generate_tests调用把估计器分配到各组合把估计器、OS、Python 版本映射为整数按OS 编号 Python 版本编号 对 3 取模匹配保证每个组合只跑约 1/3 的估计器、而每个估计器在每种 OS 与 Python 版本上至少各跑一次从而压低单次 CI 的时长与内存。默认关闭该子集分配用 pytest flagmatrixdesignTrue开启见根目录 conftest.py。7.4 如何新增测试低层测试随功能新增命名test_estimator_name.py放在模块的tests目录可用datatypes.get_examples生成示例数据、用datatypes的check_is_mtype/check_is_scitype/check_raise做数据格式校验。豁免某些测试把估计器或估计器-测试组合加入相应_config文件如EXCLUDED_TESTS/EXCLUDE_ESTIMATORS避免直接在测试里写if isinstance(object_instance, MyClass)。新增 fixture 变量一次性变量用 pytest 基础功能贯穿模块级测试的变量需在pytest_generate_tests的fixture_sequence中登记并实现_generate_变量名返回「fixture 值列表 等长命名列表」可通过test_name与前面 fixture 的值定制行为。新增/扩展场景新输入条件 → 新增场景类新方法或新调用序列 → 在现有场景的args中加键。场景通常定义args、可选的default_method_sequence/default_arg_sequence、可选的_tags、get_args与is_applicable。八、如何报告 Bug报告入口是 GitHub Issues规则见 docs/source/contributing/reporting_bugs.rst。提交前建议自查确认该问题未被现有 issues 或 pull requests 处理中所有代码片段与错误信息放在合适的代码块中明确指出涉及哪些估计器/函数以及数据形状并附上可复现的最小代码片段或 gist 链接若抛异常务必附带完整 traceback。一句话信息越具体、越可复现维护者定位越快。九、增强提案STEP重大变更的正式通道sktime 的增强提案STEP是一类软件设计文档向社区提供新设计的理由与简洁技术规格收集与讨论在独立的 enhancement-proposals 仓库进行规则见 docs/source/contributing/enhancement_proposals.rst。适用边界STEP 是提出重大变更、收集社区意见、沉淀设计决策的主要机制小改动直接在 issue 和 PR 上讨论实现即可。提交方式复制官方模板TEMPLATE.md并在提案仓库开 PR。核心建议一个 STEP 只装一个核心提案或新想法越聚焦越容易成功不确定时就拆成多个聚焦的 STEP。一份合格的 STEP 至少包含简洁的问题陈述、对解决方案的清晰描述、与备选方案的对比。sktime 总体设计原则可参考论文《Designing ML Toolboxes: Concepts, Principles and Patterns》。十、评审者指南如何 review PRreviewer_guide.rst 列出了评审者的检查清单该文档尚在完善中从三个维度展开Triage分流打上相关标签、分配到对应 project board检查标题是否用 3 字母代码如[BUG]、是否易懂检查描述是否清晰、是否关联了相关 issue/PR关注首次贡献者的 CI 检查与代码/文档质量检查是否需要帮助排查合并冲突。Code代码单测是否覆盖改动、测试是否易懂、是否所有改动都有测试覆盖——目标覆盖率达到 90% 以上CI 与 Codecov 会报告覆盖率本地运行测试确认一切正常检查公共 API 是否变化、变更前是否已加弃用警告deprecation warning。Documentation文档docstring 是否完整、对用户友好是否符合 NumPy 格式与 sktime 约定相同的参数/属性/返回值/报错在别处是否使用了尽量一致的描述在线文档渲染是否正常、是否包含指向术语表glossary与示例的链接。硬性要求PR 若不符合文档规范评审者应要求先补文档再批准合并。十一、贡献者的认可与致谢sktime 遵循 all-contributors机器可读的配置在.all-contributorsrc。如果你是首次贡献者请确保自己的名字被加入贡献者名单如果遗漏可以开 issue 或直接在 Discord 上提醒维护团队。结语从 Discord#intro的一声问候到克隆仓库、切分支、提交 PR再到用check_estimator保证接口一致、用pytest跑通三层测试、必要时提交一份聚焦的 STEP——sktime 的贡献路径清晰且对新人友好。核心要点可以浓缩为一句话公开接口不重写、实现走模板与_fit等内层方法、改动必须有测试、PR 越早开越好、文档与代码同等重要。按照本文的流程走一遍你就能从新手平稳过渡到定期贡献者甚至更进一步申请 mentoring 或成为核心开发者。延伸阅读仓库内直接可用开发环境安装docs/source/installation.rstGit 工作流docs/source/developer_guide/git_workflow.rst编码规范docs/source/developer_guide/coding_standards.rst实现估计器docs/source/developer_guide/add_estimators.rst测试框架docs/source/developer_guide/testing_framework.rst扩展模板extension_templates/接口一致性检查工具sktime/utils/estimator_checks.py包级接口测试sktime/tests/test_all_estimators.py【免费下载链接】sktimeA unified framework for machine learning with time series项目地址: https://gitcode.com/GitHub_Trending/sk/sktime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 sktime 贡献指南：从首次提交到成为核心贡献者的完整参与路径
sktime 贡献指南从首次提交到成为核心贡献者的完整参与路径【免费下载链接】sktimeA unified framework for machine learning with time series项目地址: https://gitcode.com/GitHub_Trending/sk/sktime导读sktime 是一个面向时间序列机器学习的统一框架涵盖预测、时序分类、聚类、回归、参数估计、异常检测等丰富的学习任务。本文以官方贡献指南为核心系统梳理从「在 Discord 打声招呼」到「第一个 PR 被合并」再到「持续贡献、参与评审、提交增强提案STEP」的完整参与路径并结合仓库源码说明开发环境搭建、扩展模板、check_estimator一致性测试、pytest测试框架与编码规范等关键细节。读完本文你将掌握为 sktime 提交代码、报告缺陷、评审他人 PR 以及设计重大改进的标准流程与实操命令。一、sktime 欢迎怎样的贡献sktime 的贡献指南docs/source/get_involved/contributing.rst开门见山地强调一句话We value all kinds of contributions - not just code.我们重视所有类型的贡献而不仅仅是代码。这意味着即使你不擅长写代码也可以通过以下方式参与参与社区讨论、答疑与协作编码改进文档与 docstring报告 bug、提出功能需求评审他人的 Pull Request编写并提交增强提案STEP。项目尤其鼓励新贡献者参与并且把帮助新人学习成长视为重要目标——官方 Discord 上有专门的#intro频道用于新人报到与答疑社区还会定期举办协作编程会议collab sessions与专题 stand-up 和 tech sessions。二、官方推荐的新手五步路径contributing.rst 给出了面向首次贡献者的推荐步骤在 Discord 的#intro频道打声招呼让社区认识你遇到问题也更容易获得帮助。完成开发环境搭建参见 developer guide 中的安装说明详见下文三、搭建开发环境。挑选一个合适的 first issue从项目标记了good first issue的 issue 列表中挑选一个小而简单的任务先跑通整套贡献流程。参加社区活动可以参加定期的社区协作会话community collab sessions或某个主题的 stand-up 与 tech sessions。在第一个 PR 合并后持续贡献可继续参加周五社区协作会话也可以选择申请 mentoring导师制项目获得更系统的指导。建议第一步选任务时刻意挑内容简单、改动范围小的 issue目的是先学会流程fork → 分支 → PR → 评审 → 合并而不是一上来就挑战大功能。三、搭建开发环境3.1 支持范围与安装类型根据 docs/source/installation.rst当前仓库支持的运行环境为Python 版本3.10、3.11、3.12、3.13、3.14操作系统macOS、类 Unix 系统、Windows 8.1 及以上。安装方式按使用场景分为三类稳定版生产环境、最新不稳定开发版预发布测试、完整开发者环境贡献者与第三方扩展开发者。本文聚焦最后一种。3.2 完整开发者环境contributors / extension developers 专用标准流程如下官方推荐使用 condavenv或其他虚拟环境管理器流程类似# 1. 先在 GitHub 上 fork 仓库并克隆到本地详见第四节 git clone gitgithub.com:username/sktime.git cd sktime # 2. 创建并激活虚拟环境以 conda 为例 conda create -n sktime-dev python3.11 conda activate sktime-dev # 3. 可编辑安装 开发依赖 pip install -e .[dev] # 4. 如需软依赖soft dependencies可选全量安装 pip install -e .[all_extras,dev]安装成功后会看到 successfully installed sktime 提示。仓库的依赖声明集中在 pyproject.toml其中dev依赖组已包含后续要用到的pre-commit等工具。注意all_extras只为了让全部估计器可用或运行全部测试会显著拖慢下载与测试速度普通场景建议只装核心依赖、按需补装软依赖。部分软依赖在 mac ARMM1/M2 等处理器上可能无法安装属已知问题详见安装文档的 Troubleshooting 部分。3.3 常见问题速查Module not found最常见原因是仅安装了最小依赖而所用估计器需要某个未安装的软依赖包。解决方式是补装该包或改用sktime[all_extras]全量安装。ImportError多为虚拟环境链接异常请确认环境已激活并与 IDE含 Jupyter kernel正确关联。四、Git 与 GitHub 工作流完整流程见 docs/source/developer_guide/git_workflow.rst分为一次性初始化和每次开发新功能两个部分。4.1 一次性初始化fork 并克隆仓库# 1. 在 GitHub 上点击 Fork创建你自己的副本 # 2. 克隆你的 fork 到本地 git clone gitgithub.com:username/sktime.git cd sktime # 3. 配置 upstream 远程仓库指向官方仓库 git remote add upstream https://github.com/sktime/sktime.git # 4. 验证远程配置 git remote -v # origin https://github.com/username/sktime.git (fetch/push) # upstream https://github.com/sktime/sktime.git (fetch/push)其中 Fork 操作每个 GitHub 账号只需做一次clone与upstream配置每台新机器做一次系统重装后需重做。4.2 每次开发新功能标准循环# 1. 同步 main 分支与上游 git fetch upstream git checkout main git merge upstream/main # 2. 从最新的 main 创建功能分支绝不直接在 main 上开发 git checkout -b feature-branch # 3. 开发、暂存并提交 git add modified_files git commit # 4. 推送并创建 Pull RequestWIP 阶段可先开 draft PR git push --set-upstream origin feature-branch两个值得强调的社区约定合并期间同步 mainPR 评审期间官方 main 可能持续更新用git merge而非git rebase更新你的功能分支。sktime 在 main 上会把所有 PR squash 成单个提交因此你的分支历史并不重要rebase会重写历史、可能造成难以恢复的状态官方强烈反对使用。PR 越早开越好哪怕功能未完成也建议尽早开 draft PR让社区尽早知晓你的工作并给出反馈。4.3 进阶并行分支与 PR 堆叠多任务并行每个独立任务各建一个分支严禁在同一个分支上混合多个任务否则历史混乱、评审困难、冲突风险大幅上升。PR 堆叠stacking当任务 A 是任务 B 的前置如先修 bug 再做估计器可以在 A 的分支上再开 B 的分支并各自提交 PR在 PR 描述中注明依赖关系。维护链上所有分支同步的通用做法是更新 fork → 依次把main合并进 A、把 A 合并进 B、把 B 合并进 C……逐级解决冲突。清理PR 合并后可执行git branch -D feature-branch删除本地分支用git push origin --delete feature-branch删除远端分支。五、编码规范与本地代码质量检查5.1 遵循的标准根据 docs/source/developer_guide/coding_standards.rst遵循PEP8编码指南使用ruff做代码格式化与 lintmax_line_length88其余配置见仓库根目录 pyproject.toml使用numpydoc强制 NumPy docstring 标准并叠加 sktime 特有的文档约定。5.2 sktime 特有命名与编码约定非类名用下划线分词n_instances而非ninstances例外地允许X、Y、Z及其派生名如X_train作为变量名——这是沿用 scikit-learn 生态的习惯避免一行多条语句控制流if/for后换行仓库内部引用使用绝对导入源码中禁止import *——它让符号来源不明确且会阻断 pyflakes 等静态分析工具发现 bug。5.3 用 pre-commit 自动检查pip install -e .[dev] # 确保含 dev 依赖 pre-commit install安装后每次git commit都会自动对所有改动文件运行全部代码质量检查。如需临时豁免某一行可在行尾追加# noqa: rule注释规则名参见 ruff 规则表。5.4 IDE 集成在 VS Code 中安装 ruff 扩展后它会自动读取项目pyproject.toml/ruff.toml/.ruff.toml中的配置建议同时在settings.json中加入editor.ruler: 88显示最大行长。注意 ruff 等工具需要安装到 IDE 所用的 Python 环境里通过[dev]依赖安装即可。六、实现与提交一个估计器sktime 贡献的重头戏通常是为某个 scitype学习任务类型如 forecaster、time series classifier实现新估计器详见 docs/source/developer_guide/add_estimators.rst。6.1 高层次的五步流程确定估计器的类型forecaster、classifier 等 scitype把对应类型的扩展模板extension template复制到目标位置按模板补全实现运行测试套件或check_estimator工具做接口一致性验证若测试暴露问题修复后回到第 4 步。6.2 扩展模板与双接口设计仓库的 extension_templates/ 目录为每种 scitype 提供了填空式模板包括forecasting.py、classification.py、transformer.py、clustering.py、distance_based、alignment.py、detection.py、param_est.py、split.py等。模板背后的设计是双接口模式公开接口public interface由各 scitype 的基类定义如BaseForecaster定义fit/predict遵循策略strategy模式。具体估计器永远不重写fit、predict等公开方法扩展接口extender interface模板中要求实现的是私有内层方法如_fit、_predict遵循模板template模式。样板逻辑输入检查、类型转换、自动向量化等全部沉淀在公开方法中避免像 scikit-learn 那样在每个估计器里重复check_X之类的样板。这与 scikit-learn 的扩展方式有本质区别sktime 禁止覆盖公开方法实现只发生在私有内层方法从而复用更丰富的样板逻辑如自动向量化、输入格式转换。6.3 模板中的典型 todo使用模板就是搜索todo并按提示逐项完成典型项包括确定估计器的名字与参数填充__init__把参数写入self并调用super().__init__()填写模块与类的 docstring建议在参数敲定后尽早写可当作实现规格设置估计器的tags一部分 tag 是能力声明如是否支持 nan另一部分决定内层方法看到的输入格式如X_inner_mtype。若内层实现假定numpy.ndarray或pandas.DataFrame通过 tag 声明可免去转换样板。mtype 字符串可在datatypes.MTYPE_REGISTER中找到见 sktime/datatypes/_registry.py数据类型约定的教程见 examples/AA_datatypes_and_datasets.ipynb。例如把y_inner_mtype设为pd.DataFrame就能保证_fit收到的y一定是符合 sktime 容器规范的 DataFrame实现内层方法_fit/_predict等其输入保证比公开方法更强由已设置的 tag 决定在get_test_params中填充测试参数尽量覆盖估计器内部的主要分支以提升测试覆盖。6.4 常见注意事项模板中同样有说明__init__参数写入self后不得再修改参数为估计器对象组件时一般要用sklearn.clone克隆后只在克隆体上调用方法方法应避免对入参产生副作用非状态改变的方法一般不应写self通常无需自己实现get_params/set_params——sktime的BaseEstimator继承自 scikit-learn自带实现只有异构复合结构如含嵌套估计器的 pipeline等复杂场景才需要自定义。6.5 用check_estimator验证接口一致性最快捷的验证方式是 sktime/utils/estimator_checks.py 提供的check_estimatorfrom sktime.utils.estimator_checks import check_estimator from sktime.forecasting.naive import NaiveForecaster check_estimator(NaiveForecaster)默认返回一个以测试名 fixture 组合字符串为键的dict如test_repr[NaiveForecaster-2]值要么是PASSED要么是失败时抛出的异常对象——默认不抛异常想直接抛异常便于调试传raise_exceptionsTrue只抛执行顺序中遇到的第一个异常用tests_to_run/tests_to_exclude筛选或排除测试参数为测试名不含方括号部分例如check_estimator(NaiveForecaster, tests_to_runtest_constructor) # {test_constructor[NaiveForecaster]: PASSED}用fixtures_to_run/fixtures_to_exclude筛选或排除具体 test-fixture 组合合法字符串正是默认调用返回的 dict 键例如check_estimator(NaiveForecaster, fixtures_to_runtest_repr[NaiveForecaster-2]) # {test_repr[NaiveForecaster-2]: PASSED}推荐的调试工作流① 全量运行找出失败项 → ② 用fixtures_to_run/tests_to_run收窄范围 → ③ 仍不明朗就加raise_exceptionsTrue看 traceback → ④ 还不行就在check_estimator那行代码上挂调试器。6.6 在仓库克隆中跑测试套件若估计器落在 sktime 仓库内部可直接运行基于pytest的测试套件CI/CD 同样基于 pytest。从命令行只测某个估计器pytest -k EstimatorName这与check_estimator(EstimatorName)的效果基本一致。通用接口一致性测试集中在TestAllEstimators、TestAllForecasters等类中包级测试在 sktime/tests/test_all_estimators.py模块级如 sktime/forecasting/tests/test_all_forecasters.py。pytest 生成的 test-fixture 字符串总包含估计器名作为子串与check_estimator返回的键一致因此也可以直接在代码库中按def test_xxx前缀搜索这些测试串来定位相关测试源码。6.7 第三方扩展包中的测试第三方扩展包开源或闭源可通过三种方式复用 sktime 的接口一致性测试直接导入check_estimator它可以在unittest、pytest等任意测试框架中运行导入parametrize_with_checks同样位于sktime.utils.estimator_checks在 pytest 套件中把一组估计器类/实例参数化到独立测试用例from sktime.utils.estimator_checks import parametrize_with_checks parametrize_with_checks(OBJS_TO_TEST) def test_sktime_api_compliance(obj, test_name): check_estimator(obj, tests_to_runtest_name, raise_exceptionsTrue)直接继承测试类如test_all_estimators.TestAllEstimators、test_all_forecasters.TestAllForecasterspytest 会自动发现。6.8 把估计器并入 sktime 本体时的额外要求满足文档规范docs/source/developer_guide/documentation.rst在 docs/source/api_reference 下对应的.rst文件中登记到 API 参考作者应把自己加入估计器的authors和maintainerstag若依赖/新增软依赖需遵循 docs/source/developer_guide/dependencies.rst 中的步骤保证估计器在目标位置通过完整本地测试pytest -k EstimatorNameget_test_params的测试参数应控制在秒级运行时长以适配远程 CI/CD。依赖 Cython 的估计器有专门流程C 代码放在独立的sktime-cython包中不得直接进入 sktimesktime 内只放继承自 base class 的接口层并设置python_dependenciessktime-cython与tests:vmTrue。第三方 Cython 估计器则建议代码放在自有包home-package中sktime 内通过转发接口如_placeholder_record模板或 delegator 模式接入。七、测试框架一览sktime 用pytest做估计器接口合规与代码正确性测试框架说明见 docs/source/developer_guide/testing_framework.rst。7.1 三层测试架构测试与估计器的继承层次大致对应分三层包级package level校验BaseObject/BaseEstimator规范合规位于 sktime/tests/test_all_estimators.py模块级module level校验具体估计器与其 scitype 基类的一致性如 sktime/forecasting/tests/test_all_forecasters.py、distances/tests/test_all_dist_kernels.py等低层low level在tests文件夹中按文件测试单个功能。约定每个模块含tests目录tests目录可含_config.py收集模块级测试配置通用测试工具位于sktime.utils._testing。7.2 核心机制fixture 参数化与场景scenariosktime 通过向pytest_generate_tests注册的插件自动为 fixture 生成参数化循环开发者写测试时无需手写循环。典型的接口测试长这样def test_fit_returns_self(object_instance, scenario): Check that fit returns self. fit_return scenario.run(object_instance, method_sequence[fit]) assert ( fit_return is object_instance ), fEstimator: {object_instance} does not return self when calling fitobject_instance由create_test_instances_and_names根据各估计器get_test_params构造的全部测试实例scenario封装数据输入与调用序列的对象scenario.run等价于按scenario_kwargs调用fit(**kwargs)等。sktime 的pytest_generate_tests只把对当前估计器适用的 scenario 传给测试。场景定义示例来自utils/_testing/scenarios_forecastingclass ForecasterFitPredictUnivariateNoXLateFh(ForecasterTestScenario): Fit/predict only, univariate y, no X, no fh in predict. _tags {univariate_y: True, fh_passed_in_fit: False} args { fit: {y: _make_series(n_timepoints20, random_stateRAND_SEED)}, predict: {fh: 1}, } default_method_sequence [fit, predict]scenario.run(object_instance)会先fit(y...)再predict(fh1)并返回结果。场景还有is_applicable(estimator)判断是否适用如单变量场景对多元 forecaster 不适用并且场景继承BaseObject因此复用 sktime 的 tag 系统。7.3 远程 CI 的矩阵分配策略远程 CI 在所有受支持 OS × Python 版本组合上运行三层测试但通过subsample_by_version_os位于tests.test_all_estimators由BaseFixtureGenerator的pytest_generate_tests调用把估计器分配到各组合把估计器、OS、Python 版本映射为整数按OS 编号 Python 版本编号 对 3 取模匹配保证每个组合只跑约 1/3 的估计器、而每个估计器在每种 OS 与 Python 版本上至少各跑一次从而压低单次 CI 的时长与内存。默认关闭该子集分配用 pytest flagmatrixdesignTrue开启见根目录 conftest.py。7.4 如何新增测试低层测试随功能新增命名test_estimator_name.py放在模块的tests目录可用datatypes.get_examples生成示例数据、用datatypes的check_is_mtype/check_is_scitype/check_raise做数据格式校验。豁免某些测试把估计器或估计器-测试组合加入相应_config文件如EXCLUDED_TESTS/EXCLUDE_ESTIMATORS避免直接在测试里写if isinstance(object_instance, MyClass)。新增 fixture 变量一次性变量用 pytest 基础功能贯穿模块级测试的变量需在pytest_generate_tests的fixture_sequence中登记并实现_generate_变量名返回「fixture 值列表 等长命名列表」可通过test_name与前面 fixture 的值定制行为。新增/扩展场景新输入条件 → 新增场景类新方法或新调用序列 → 在现有场景的args中加键。场景通常定义args、可选的default_method_sequence/default_arg_sequence、可选的_tags、get_args与is_applicable。八、如何报告 Bug报告入口是 GitHub Issues规则见 docs/source/contributing/reporting_bugs.rst。提交前建议自查确认该问题未被现有 issues 或 pull requests 处理中所有代码片段与错误信息放在合适的代码块中明确指出涉及哪些估计器/函数以及数据形状并附上可复现的最小代码片段或 gist 链接若抛异常务必附带完整 traceback。一句话信息越具体、越可复现维护者定位越快。九、增强提案STEP重大变更的正式通道sktime 的增强提案STEP是一类软件设计文档向社区提供新设计的理由与简洁技术规格收集与讨论在独立的 enhancement-proposals 仓库进行规则见 docs/source/contributing/enhancement_proposals.rst。适用边界STEP 是提出重大变更、收集社区意见、沉淀设计决策的主要机制小改动直接在 issue 和 PR 上讨论实现即可。提交方式复制官方模板TEMPLATE.md并在提案仓库开 PR。核心建议一个 STEP 只装一个核心提案或新想法越聚焦越容易成功不确定时就拆成多个聚焦的 STEP。一份合格的 STEP 至少包含简洁的问题陈述、对解决方案的清晰描述、与备选方案的对比。sktime 总体设计原则可参考论文《Designing ML Toolboxes: Concepts, Principles and Patterns》。十、评审者指南如何 review PRreviewer_guide.rst 列出了评审者的检查清单该文档尚在完善中从三个维度展开Triage分流打上相关标签、分配到对应 project board检查标题是否用 3 字母代码如[BUG]、是否易懂检查描述是否清晰、是否关联了相关 issue/PR关注首次贡献者的 CI 检查与代码/文档质量检查是否需要帮助排查合并冲突。Code代码单测是否覆盖改动、测试是否易懂、是否所有改动都有测试覆盖——目标覆盖率达到 90% 以上CI 与 Codecov 会报告覆盖率本地运行测试确认一切正常检查公共 API 是否变化、变更前是否已加弃用警告deprecation warning。Documentation文档docstring 是否完整、对用户友好是否符合 NumPy 格式与 sktime 约定相同的参数/属性/返回值/报错在别处是否使用了尽量一致的描述在线文档渲染是否正常、是否包含指向术语表glossary与示例的链接。硬性要求PR 若不符合文档规范评审者应要求先补文档再批准合并。十一、贡献者的认可与致谢sktime 遵循 all-contributors机器可读的配置在.all-contributorsrc。如果你是首次贡献者请确保自己的名字被加入贡献者名单如果遗漏可以开 issue 或直接在 Discord 上提醒维护团队。结语从 Discord#intro的一声问候到克隆仓库、切分支、提交 PR再到用check_estimator保证接口一致、用pytest跑通三层测试、必要时提交一份聚焦的 STEP——sktime 的贡献路径清晰且对新人友好。核心要点可以浓缩为一句话公开接口不重写、实现走模板与_fit等内层方法、改动必须有测试、PR 越早开越好、文档与代码同等重要。按照本文的流程走一遍你就能从新手平稳过渡到定期贡献者甚至更进一步申请 mentoring 或成为核心开发者。延伸阅读仓库内直接可用开发环境安装docs/source/installation.rstGit 工作流docs/source/developer_guide/git_workflow.rst编码规范docs/source/developer_guide/coding_standards.rst实现估计器docs/source/developer_guide/add_estimators.rst测试框架docs/source/developer_guide/testing_framework.rst扩展模板extension_templates/接口一致性检查工具sktime/utils/estimator_checks.py包级接口测试sktime/tests/test_all_estimators.py【免费下载链接】sktimeA unified framework for machine learning with time series项目地址: https://gitcode.com/GitHub_Trending/sk/sktime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考