人工智能AutoML机器学习【免费下载链接】auto-sklearnAutomated Machine Learning with scikit-learn项目地址https://gitcode.com/gh_mirrors/au/auto-sklearn点击查看免费下载本文以 auto-sklearn 官方贡献指南CONTRIBUTING.md为主体系统梳理了向该项目提交代码的完整链路Fork 与克隆含automl_common子模块、分支与虚拟环境搭建、Bug 修复 / 文档 / 新功能三类贡献的编写规范、本地测试与文档构建、代码格式化检查以及最终创建 Pull Request 并被评审合并的全过程。读完本文你将能够按照官方认可的 Gitflow 式流程独立完成一次从改代码到被合并的 auto-sklearn 贡献。为什么需要一套规范的贡献流程auto-sklearn 是一个长期迭代、被广泛用于各类自动化机器学习场景的成熟项目。像所有持续演进的软件一样它也会存在新旧 bug依赖升级与新功能引入也会带来新的问题。为了在多人协作下保持主干稳定、代码风格统一、文档可维护项目维护了一套明确的分支策略与检查流水线所有新改动先进入development分支积累验证验证通过后再发布为 master 版本。因此任何贡献——无论是一行文档的 typo 修正、一个小 bug 修复还是全新的功能——都需要经过格式化、静态检查、测试与文档构建等若干关卡。这份指南覆盖的正是这些关卡的具体操作它们大多被封装在仓库根目录的 Makefile 中可用make help一览全部目标make help输出会列出install-dev、check、format、pre-commit、doc、links、examples、publish、test等常用目标。下文将逐一讲解。开发前的环境准备1. Fork 并克隆你自己的仓库第一步是在代码托管平台上创建 auto-sklearn 的 fork这样你可以在不影响原仓库任何代码的前提下自由修改。fork 会复制仓库全部内容包括所有分支。克隆时务必注意--recurse-submodules参数auto-sklearn 通过子模块方式引入autosklearn/automl_common仓库中的 autosklearn/automl_common 目录即由该子模块提供必须一并下载。# 以 https 方式克隆你的 fork请将 your-username 替换为你自己的用户名 git clone --recurse-submodules https://your-username/auto-sklearn # ... 或者使用 ssh git clone --recurse-submodules gityour-username:auto-sklearn.git # 进入克隆目录 cd auto-sklearn2. 从 development 分支创建新分支所有贡献都应当基于最新的development分支展开而不是 master# 基于 development 创建新分支 git checkout -b my_new_branch development # 如果克隆时漏掉了 --recurse-submodules或需要手动初始化子模块 git submodule update --init --recursive也可以采用更手动的方式# 查看所有分支当前分支前会有 * 标记 git branch # 切换到 development 分支 git checkout development # 基于当前活动分支创建新分支 git checkout -b my_new_branch之所以坚持新建分支原因有二一是让合并进上游的提交历史保持干净整洁二是后续一旦需要rebase或merge独立分支会容易得多。3. 创建并激活虚拟环境强烈建议使用 Python 虚拟环境将项目依赖与系统环境隔离# 在名为 my-virtual-env 的目录中创建虚拟环境 python -m venv my-virtual-env # 激活虚拟环境 source my-virtual-env/bin/activate激活后所有pip install安装的包都会进入该虚拟环境在其中运行的任何 python 都能访问这些包。需要退出时执行deactivate或直接关闭终端。两点提醒如果你本机的 Python 版本是 3.6 或更低auto-sklearn 不支持从 setup.py 的启动检查可以看到项目要求Python 3.7 及以上。此时可借助 pyenv 等工具在 Python 版本间灵活切换。conda 也是管理 Python 项目的常用替代方案。4. 安装开发依赖仓库提供了现成的make目标make install-dev等价于手动执行pip install -e .[test,examples,doc] # 如果使用 bash 以外的 shell需加引号 pip install -e .[test,examples,doc]这里的关键点pip install -e .注意结尾的点表示以可编辑模式安装当前目录下的包改动源码后无需重新安装即可生效[test,examples,doc]是extras_require中的三组可选开发依赖。查看 setup.py 可知其具体构成test组包含 pytest 全家桶pytest-cov、pytest-forked、pytest-timeout、pytest-cases、mypy、isort、black、pydocstyle、openml、pre-commit等examples组包含 matplotlib、jupyter、seaborndocs组包含 sphinx、sphinx-gallery、numpydoc 等这些依赖只在开发时使用运行 auto-sklearn 本身并不需要。从 Makefile 可以看到install-dev还会顺带执行pre-commit install把格式检查钩子接入你的 git 提交流程。三类核心贡献及其编写要点项目把贡献归纳为文档Documentation、Bug 修复Bug Fixes与新功能Features三类各有不同的工作流侧重。当然不必被这三个标题限制补充测试、改进函数与方法的类型标注、合规性调整同样非常有用。Bug 修复修复 bug 时有三个核心问题需要思考能复现 bug 的最小可运行示例是什么这通常是第一步。构造最小复现代码的过程本身就常常能照亮需要修复的位置。快速修复是什么长期修复又是什么有时只是一个 typo改一行即可有时 bug 是某个被忽视的更深层问题的表象可能需要重构。如果属于后者请在动手时及时告知维护者——如果改动涉及默认行为或公共 API 这类破坏性变更往往需要先行沟通。一个经验法则如果修复需要改动超过 50–100 行代码最好先和团队讨论如何下手。如何为这个 bug 编写测试防止它将来复发最小复现示例的大部分内容通常可以直接转化为一条回归测试。修复完成后一份好的 PR 描述见下文创建 PR应当说明你是如何定位该 bug 的、问题根因是什么、以及是如何修复的。文档auto-sklearn 的全部文档使用 Sphinx 生成扩展配置见 doc/conf.py包括sphinx.ext.autodoc、sphinx.ext.autosummary、numpydoc、sphinx_gallery.gen_gallery等。修改文档后先按下文测试一节构建文档再用浏览器打开doc/build/html/index.html查看效果。纯 typo 修复直接提交 PR 即可通常会被快速接受。修复链接需要了解 Sphinx 的链接机制。链接内部文档先用.. _mylabel:创建标签再以:ref:引用.. _mylabel: I am reference to :ref:the above labelmylabel链接外部文档写成链接文字URL_的形式注意结尾的下划线_必不可少Heres a link..._ to the external documentation on linking for sphinx为某个功能撰写更详细的文档可以考虑三点——能否附上一段代码片段来示意文档或代码中是否有其他相关部分值得互相链接读者需要预先了解 auto-sklearn 的哪些内容如有需要就链接到对应章节。贡献示例example这是演示某个功能完整流程的最佳方式。sphinx-gallery 会运行示例目录下所有example_*.py文件把 ReStructured Textrst说明与 python 代码及其输出合并渲染到同一个 HTML 页面。仓库中的示例按主题分目录组织例如 examples/20_basic、examples/40_advanced、examples/60_search、examples/80_extending可以参考其中已有文件如 examples/40_advanced/example_calc_multiple_metrics.py学习如何在.py文件中嵌入 rst。新功能新功能通常是更大的工程官方强烈建议先与维护者沟通一方面确认该功能是否适合放进 auto-sklearn有些功能更适合留给外部库或集成层另一方面在动手前把功能的形态敲定功能越直接、越聚焦越好。开发新功能时要注意新功能是否会改变任何现有默认行为对老用户而言意外且未经预告的行为变化是有害的。有时不得不改但更多时候可以把新功能做成一个由用户自行启用的选项。如果要引入新的 API先写出你期望的用法示例确认现有代码中是否已有可实现同样效果的途径是否要弃用deprecate现有 API——这是一个必须提前讨论的重要问题。测试新功能新功能意味着新 bug所以要尽量覆盖你能想到的每一个场景覆盖得越多越好。测试没有捷径通常的做法就是穷举常见用例。文档化新功能如果功能由某个参数开启那么大部分文档其实已经存在于代码 docstring 中——它会被自动渲染进在线文档——前提是你改代码时更新了那条 docstring。如果新功能无法用简单参数描述清楚可以考虑在 doc/manual.rst 中补充一小段说明。如果这个功能足够亮眼不妨再写一个example_*.py它会被运行并渲染进在线文档。本地测试测试、文档与代码质量运行测试改动完成后先完整跑一遍测试pytest完整测试可能耗时较长可以用pytest --help了解如何只运行上次失败的用例或只运行特定用例从而加速迭代但在最终提交前务必完整执行一次pytest。以下是一些特别实用的用法# 运行特定文件如 test_estimators.py pytest test/test_automl/test_estimators.py # 运行整个目录的测试如 pipeline pytest test/test_pipeline # 运行特定目录中的特定测试 pytest -k test_mytest test/test_automl # 只重跑上一次 pytest 中失败的测试 pytest --last-failed # 重跑全部测试但失败的优先执行 pytest --failed-first # 遇到第一个失败即退出 pytest -x仓库的 pytest 配置在 pyproject.toml 中testpaths [test]、addopts --forked每个测试在独立进程中运行。测试代码位于 test 目录按模块组织例如 test/test_automl、test/test_pipeline、test/test_estimators 等。完整跑一遍单测可能较慢可以并行执行export OPENBLAS_NUM_THREADS1 export MKL_NUM_THREADS1 export OMP_NUM_THREADS1 pytest -n 4PyCharm 等更高级的编辑器还内置了 pytest 集成值得一试。构建文档项目使用 Sphinx 生成文档可以读取代码中的注释与 docstring 生成 HTMLmake doc如果改动涉及文档还有links命令检查所有链接是否正确指向目标有助于发现死链或笔误make linkssphinx-gallery 可以把examples文件夹中的 python 文件运行起来生成同时展示代码与输出的 HTMLmake examples从 Makefile 可以看到make doc实际执行的是sphinx-build -b html且关闭示例绘图SPHINX_GALLERY_PLOTFalse而make examples才会生成完整画廊。构建完成后用浏览器打开doc/build/html/index.html# Firefox firefox ./doc/build/html/index.html # 使用默认浏览器 xdg-open ./doc/build/html/index.html格式与静态检查所有改动通过测试后还要确保代码风格统一、类型标注正确。项目使用black与isort自动格式化并排序 importmake format随后用 black、isort、mypy、flake8、pydocstyle 做全面检查make check从 Makefile 可以看到make check包含check-black、check-isort、check-mypy、check-flake8四步pydocstyle 由于多数模块尚无法通过而默认被注释关闭。这些工具的关注点分别是无多余空格与空行、行长不超标flake8、black多来源代码保持一致的观感blackimport 顺序一致isort函数具备类型注解且通过静态类型检查mypy函数与类具备 docstringpydocstyle。如果你对 Python 类型标注还不熟悉或不确定某处该如何标注可以直接提交 PR维护者会在评审中帮你。pre-commit 钩子如果通过make install-dev安装pre-commit 已经就绪每次提交时它都会自动运行并提示问题。也可以手动安装pre-commit install手动运行全部钩子pre-commit run --all-filespre-commit 的配置位于 .pre-commit-config.yaml包括 isort、black、mypy、flake8 钩子pydocstyle 钩子因多数模块无法通过而被显式禁用files: DISABLED。其余工具主要配置在 pyproject.toml 与.flake8中。创建 Pull Request提交并推送本地检查全部通过后提交改动并推送到你的 fork# 查看所有改动的文件概览 git status # 添加你改动的文件 git add {changed files} git commit -m Something as meaningful as possible # 将 my_new_branch 推送到位于 origin 的 fork git push --set-upstream origin my_new_branch发起 PR然后到你的 fork 仓库页面点击Contribute按钮选择目标分支为automl/auto-sklearn的development分支方向如下automl/auto-sklearn | development - your-username/auto-sklearn | my_new_branch之所以不把新 PR 直接合入 master是为了始终保证有一个稳定版本改动先在 development 分支上积累确认彼此兼容后再形成新的 master 版本。PR 描述中建议包含所做改动的高层概览修复了什么问题或引入了什么功能纯文档修复则不必过于在意是否引入了破坏性 API 变更——评审时可能注意不到提前说明会很有帮助你认为该改动未来可能带来什么影响后续工作会是什么样若是新功能写明谁会使用它、附一段简短的代码示例并说明你是如何测试的若是 bug 修复说明该 bug 为什么会存在、你如何解决、以及测试如何确保它不再出现。提交后的自动检查与评审PR 提交后项目配置了自动流水线GitHub 会自动调度单元测试与文档构建并做快速代码质量检查你可以在Checks标签页或 PR 底部看到结果。如果出现红叉通常意味着有本地测试本应捕获的问题或是在你未开发过的环境中出现了状况也有小概率是与你改动无关的既有问题此时可以随时提问。与此同时维护者会评审你的代码。常见的评审意见包括这里看起来有点怪为什么这么做能不能复用 X 处的现有功能能否为此补充测试或文档有没有更优雅的做法评审、修改、再测试的过程可能循环数轮。最高效的做法是在本地把测试、格式检查与文档构建全部跑通——本地全绿的话自动化测试通常也不会有问题。一旦双方满意维护者会以 squash压缩合并方式将改动合入 development 分支你的贡献就正式进入 auto-sklearn 了。快速上手Pull Request 速查清单如果你已熟悉开源贡献流程直接照此执行# 克隆你的 fork 并从 development 创建新分支 git clone gityour-username:auto-sklearn.git cd auto-sklearn git checkout -b my_new_branch development # 初始化 autosklearn/automl_common 子模块 git submodule update --init --recursive # 创建并激活虚拟环境避免包冲突 python -m venv my-virtual-env source my-virtual-env/bin/activate make install-dev # pip install -e .[test,docs,examples] # 手动安装的方式 # 编辑文件... # 格式化代码 make format # 检查问题 make check # ... 修复问题 # 如果改动了文档 # 生成全部文档并检查链接 make doc make links make examples # 修改了示例时才需要 # ... 修复问题 # 如果改动了代码运行测试可用 pytest --help 了解如何只跑特定用例 pytest # ... 修复问题 # 可选运行 pre-commit即 GitHub 上执行的格式检查 pre-commit install pre-commit run --all-files # ... 修复问题 # 检查改动文件 git status # 提交改动 git add {changed files} git commit -m Meaningful as you can make it message # 推送回你的 fork git push --set-upstream origin my_new_branch随后到你的 fork 页面点击Contribute按钮发起 PR目标为development分支automl/auto-sklearn | development - your-username/auto-sklearn | my_new_branch在描述中说明改了什么、为什么改、以及可能的影响。维护者看到后会运行与本地相同的自动化测试并评审代码必要时要求修改最终双方满意后即合并。常见问题FAQ我的 PR 已经完成或有新改动想被评审接下来怎么办维护者会主动关注进行中的 PR。当你认为 PR 已就绪或需要一些反馈时可以在 PR 下留言并 维护者如 eddiebergman 或 mfeurer他们会尽快给出反馈。我被要求 rebase 我的 PR为什么该怎么做经常发生的情况是在你开发期间development 分支上又合并了新的内容。由于你的分支基于旧的 development 创建本地与 fork 中缺少这些新改动。如果你们改动了不同的代码区域通常可以直接合并但如果被要求 rebase说明存在无法自动合并或可能重叠的改动。操作分三步先更新你 fork 上的 development 分支最省事的方式是到你的 fork 仓库页面切到 development 分支并点击fetch upstream让 fork 与上游保持同步。在本地克隆中拉取这些新改动git checkout development git pull将 my_new_branch 变基到新的 development 之上git checkout my_new_branch git rebase development如果没有冲突到此即可恢复正常工作。若有冲突需要逐个解决可查阅你所用平台关于 git rebase 冲突解决的文档。工具链配置速览为了让上述流程真正落地仓库在配置层面做了完整支撑贡献者可直接查阅Makefileinstall-dev、check、format、doc、links、examples、test、publish等开发目标的定义如check由 black/isort/mypy/flake8 四个子检查组成test实际执行python -m pytest testsetup.pytest、examples、docs三组可选依赖的具体清单以及 Python ≥ 3.7、POSIX 系统的启动校验pyproject.tomlpytest--forked模式、测试路径、black目标 Python 3.7、isortblack profile、分区与排序规则、跳过automl_common、pydocstylenumpy 约定及忽略规则、mypy强制全量类型标注、各模块 override的集中配置.pre-commit-config.yaml提交时自动执行的 isort / black / mypy / flake8 钩子及各钩子作用的目录范围doc/conf.pySphinx 扩展与 sphinx-gallery 配置示例目录指向 examplesdoc/Makefile文档构建的html、html-noexamples、linkcheck等底层目标。遵循这份指南完成一次贡献本质上就是与项目维护团队建立共同节奏的过程干净的分支、可复现的 bug 用例、覆盖到位的测试、风格统一的代码、以及说清楚为什么的 PR 描述。跑通本地全部检查往往就意味着自动化流水线也会顺利通过。赞分享人工智能AutoML机器学习【免费下载链接】auto-sklearnAutomated Machine Learning with scikit-learn项目地址https://gitcode.com/gh_mirrors/au/auto-sklearn点击查看免费下载相关推荐MMPose 贡献指南从 Fork 到 Pull Request 的完整开源协作流程MMPose 贡献指南从 Fork 到 Pull Request 的完整开源协作流程 MMPose 是 OpenMMLab 团队开源的姿态估计工具箱与基准库计算机视觉人工智能深度学习MSEdgeRedirect开源贡献工作流从Fork到Pull Request的完整流程MSEdgeRedirect开源贡献工作流从Fork到Pull Request的完整流程 你是否曾想为MSEdgeRedirect项目贡献代码但不知从何入手桌面应用HuLa 开源贡献指南从 Fork 到 Pull Request 的完整协作流程HuLa 开源贡献指南从 Fork 到 Pull Request 的完整协作流程 本文以仓库根目录的 CONTRIBUTING.md https://link即时通讯前端桌面应用移动开发上一篇SMUDebugTool硬件调试工具完全指南下一篇PlayIntegrityFix完整指南Root设备完整性验证终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
