为 Material for MkDocs 贡献代码从 Fork 到合入的 Pull Request 完整实操指南【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-materialMaterial for MkDocs 是一个活跃维护、持续演进的开源项目任何人都可以通过提交 Pull RequestPR贡献 bug 修复、文档改进或新功能。本文以仓库中的贡献指南 making-a-pull-request.md 为骨架完整讲解从创建 Fork、搭建开发环境、topic 分支开发、合并上游并发变更到创建草稿 PR、接受评审、最终合入的每一步细节同时结合仓库中的开发环境配置customization.md、构建脚本package.json与内置 info 插件src/plugins/info/plugin.py源码为你提供一份可直接照着执行、经得起评审检验的贡献指南。贡献前的第一原则先讨论再动手在投入精力修改代码、创建 PR 之前请务必先在社区里说明你的意图。这是整个贡献流程的起点能避免大量返工如果你认为发现了 bug请先提交一份 bug 报告如果你打算改进文档请先创建一个 文档问题如果你想开发新功能请先提交一份 变更请求。请认真参考这些指南给出的建议。你要解决的问题可能已经存在更简单的解法也可能通过配置或 定制化 就能实现未必需要改动项目源码。项目整体的贡献入口与各类模板的选择可以参考 贡献总览。先掌握 Pull Request 的基础知识Pull Request 是 Git 托管服务本项目使用 GitHub在 Git 之上封装的一种协作概念。开始之前建议先熟悉 GitHub 官方文档中的几篇文章Forking a repositoryFork 仓库Creating a pull request from a fork从 Fork 创建 PRCreating a pull request创建 PR。这些官方文章针对不同操作系统和不同的 GitHub 交互方式提供了定制化说明。本指南描述的是适用于 Material for MkDocs 的流程无法覆盖所有工具组合与操作方式的排列组合因此理解 PR 的一般概念是继续的前提。Pull Request 全流程总览先建立 3 万英尺的整体视角再进入具体命令。整个流程分为两个阶段准备变更并创建草稿 PR以及收尾评审并合入。准备变更与创建草稿 PR下面的时序图描述了准备 PR 时各仓库之间典型的流转关系在主仓库 Fork 出你的仓库 → clone 到本地 → 创建 topic 分支 → 迭代编辑与推送 → 同步上游变更 → 创建草稿 PR 并接受评审。sequenceDiagram autonumber participant mkdocs-material participant PR participant fork participant local mkdocs-material - fork: fork on GitHub fork - local: clone to local local - local: branch loop prepare loop push loop edit local - local: commit end local - fork: push end mkdocs-material - fork: merge in any changes fork - PR: create draft PR PR - PR: review your changes end具体步骤如下创建 ForkFork 一份 Material for MkDocs 仓库得到一份你有权限推送的仓库副本。注意同一个仓库在同一时间只能存在一个 Fork你创建的 Fork 就是你的那一个。Clone 到本地把 Fork 克隆到本地机器开始修改工作。创建 topic 分支所有贡献都应通过一个名称能描述所做事宜的 topic 分支进行。这允许你同时进行多项工作如果与公共版本协作也能让他人明确看到这些代码是进行中的工作。topic 分支生命周期相对短暂当你的变更被并入代码库后它就会消失。如需改代码搭建开发环境如果打算修改代码而不仅是文档需要先 搭建开发环境下面有完整步骤。迭代编辑与提交编辑、提交是迭代过程。请以合理的块为单位提交——每个 commit 代表一段完整的工作而不是一次性把所有内容堆进一个提交。细粒度、增量式的提交远比一次提交、四处开花、牵涉大量文件的大变更容易评审。尽量让变更保持小且局部化提交时始终想着评审者尤其要写有意义的提交信息。定期推送把工作定期推送到你的 Fork。同步上游变更随时关注所克隆的 Material for MkDocs 仓库的变化。如果工作周期较长这一点尤其重要——请定期把并发产生的变更合并进你的 Fork 和分支。创建 PR 之前至少必须做一次越频繁越好以把冲突风险降到最低。创建草稿 PR当变更处于你能在草稿 PR 中描述它们的状态时创建草稿 PR并引用促成这项工作的任何既有讨论或 issue。草稿是尽早从维护者或其他贡献者获得反馈的好方式你可以在你认为重要的节点显式请求评审。自查并迭代把自己当作评审者审查自己的工作修复发现的问题。批判性地查看所改文件的 diff特别关注变更是否尽可能小、是否符合项目通用编码风格。收到反馈后按需对上述流程迭代。补充验证提交前至少用若干项目验证变更。必须确保不破坏 Material for MkDocs 自身文档的构建文档位于仓库的docs目录同时可选用示例项目验证相关示例仍能正常构建。收尾正式评审与合入当你满意于自己的变更时进入收尾阶段——把 PR 正式化并请求更正式、更详细的评审。sequenceDiagram autonumber participant mkdocs-material participant PR participant fork participant local activate PR PR - PR : finalize PR loop review loop discuss PR - PR: request review PR - PR: discussion local - fork: push further changes end PR - mkdocs-material: merge (and squash) deactivate PR fork - fork: delete branch mkdocs-material - fork: pull local - local: delete branch fork - local: pull endFinalize正式化当你确信所作变更足以构成维护者可并入代码库的贡献时将 PR 正式化。这向所有人表明你认为工作完成可以进入接受与合入视角的评审。请求评审向维护者请求评审。讨论与修改维护者可能对你的代码发表评论请与他们讨论。注意维护者的视角可能与你不同——他们更多从项目长期维护的角度出发而你更聚焦于自己解决的具体问题或特性。请始终保持相互尊重的讨论。请理解并非所有 PR 都会被并入代码库。原因多种多样工作可能暴露出阻碍合入的其他问题有时它揭示了更好的做法或说明需要更通用的方案。这些都正常即使具体变更最终未被接受也有助于项目前进。按反馈迭代把要求的修改提交到本地 clone 并推送到 ForkPR 会自动更新。一个贡献可能需要多次迭代才能达到可接受状态。认真阅读每条评论、谨慎修改能显著加快流程。合入可能 squash评审者完全满意后将变更合入主分支。过程中评审者可能把多个 commitsquash压缩成更少的提交并可能编辑提交信息。恭喜——你现在已经为项目做出了贡献变更会以你的名义出现在主分支中。清理你可以删除 Fork 和本地仓库下次重新开始也可以保留它们但后续任何工作都必须与上游保持同步。推荐从删除 Fork 上的分支开始。同步合并结果为确保拿到你产出的变更把主仓库的变更 pull 到 Fork 的 master 分支。删除本地 topic 分支同样从本地 clone 中删除 topic 分支。同步本地 master把变更 pull 到本地 clone 的 master 分支。分步实操指南下面是具体指令与技巧。本指南默认使用 Git 命令行工具对于大多数替代方案IDE、GitHub 网页界面提供的功能从命令行指令转换过去并不困难仅在必要时补充说明。Fork 仓库要对 Material for MkDocs 做修改先在 GitHub 上 Fork 其仓库这样你就拥有一个可推送变更的 GitHub 仓库只有维护者和协作者对原始仓库有写权限。无论修改代码还是文档都请 Fork 该仓库。建议把仓库名追加-fork后缀让看到它的人明白这是一个临时 Fork 而非原始仓库或项目的长期分支也可以加一段说明用途的描述。搭建开发环境从这一步开始请完整执行开发环境搭建流程原始指南指向 customization.md#environment-setup此处展开完整命令以便在可修改、可评审、可测试的环境中工作克隆仓库git clone https://github.com/squidfunk/mkdocs-material cd mkdocs-material创建并激活 Python 虚拟环境python -m venv venv source venv/bin/activate!!! note 确保 pip 始终在虚拟环境中运行 设置环境变量PIP_REQUIRE_VIRTUALENVtrue后pip会拒绝在虚拟环境之外安装任何东西。忘记激活venv会随着时间在环境外安装各类包可能引发更多错误。建议把它写进.bashrc或.zshrc并重启 shell export PIP_REQUIRE_VIRTUALENVtrue 安装 Python 依赖git、recommended、imaging是 pyproject.toml 中定义的扩展依赖组imaging用于社交卡片等图片生成pip install -e .[git, recommended, imaging] pip install nodeenv此外还需在系统中安装cairo与pngquant库具体见 image-processing.md 说明。安装 Node.js 与前端依赖把 Node.js LTS 版本装进 Python 虚拟环境再安装全部 Node 依赖nodeenv -p -n lts npm install进入开发模式一个终端运行 watcher 持续编译主题源码npm start另一个终端启动 MkDocs 实时预览服务器mkdocs serve --watch-theme浏览器访问 localhost:8000 即可看到本项目文档的实时构建。!!! warning 不要修改material目录 永远不要在material目录中做任何修改——该目录的内容由src目录自动生成主题构建时会整体覆盖。构建主题完成修改后执行npm run build触发所有样式表与 JS 文件的编译和压缩产物位于material目录再运行mkdocs build就能看到你的改动生效。如果改了项目自身的 overrides比如提交 PR 前需要构建全部内容用npm run build:all耗时更长会额外构建图标搜索索引、schema 文件以及附加样式与脚本。!!! note 源码布局与自检 主题真正的源码在 src/templates含 main.scss 与 bundle.ts与 src/pluginspackage.json 还提供了npm run checkTypeScript 类型检查check:build与 stylelint/eslint 风格检查check:style用于提交前自检。修改代码与文档修改代码或文档时请遵循项目既有风格这能提高可读性也让评审者更容易读 diff。避免做大规模风格变更比如让 IDE 重新格式化所有代码。动手修改前认真研究你要改动的代码确保完全理解其工作原理。这不仅能帮你解决问题也能把产生非预期副作用的概率降到最低。提交到分支PR 的开发最好放在独立于master的 topic 分支上进行。创建新本地分支并提交git switch -c name推送到 Fork 时使用git push -u origin name-u是--set-upstream的简写它让新分支跟踪Fork 中同名的分支——之后默认的pull和push都会作用于 Fork 里的那个分支。合并并发变更工作周期越长主仓库在此期间产生新变更的概率越大。建议把原始 Material for MkDocs 仓库设置为本地 clone 的upstream远端$ git remote -v origin gitgithub.com:your_username/mkdocs-material-fork.git (fetch) origin gitgithub.com:your_username/mkdocs-material-fork.git (push) $ git remote add upstream https://github.com/squidfunk/mkdocs-material.git $ git remote -v origin gitgithub.com:alexvoss/mkdocs-material-fork.git (fetch) origin gitgithub.com:alexvoss/mkdocs-material-fork.git (push) upstream https://github.com/squidfunk/mkdocs-material.git (fetch) upstream https://github.com/squidfunk/mkdocs-material.git (push)之后就能直接把并发变更从 upstream 拉到本地 clone在本地完成必要的合并再推送到你的 Fork。注意 pull 时必须显式指定远端# 先在本机做并提交一些本地修改 push pull upstream master这条命令把master分支的变更拉进你的 topic 分支并合并它们。测试与审查变更提交任何变更之前必须确认其行为符合预期且不产生非预期副作用。至少在以下三组冒烟测试上验证项目自身文档按 customization.md#environment-setup 搭好环境后mkdocs serve应持续构建文档。检查没有错误信息理想情况下也没有新增的警告。一个代表问题或新特性的测试项目如果你为 bug 提交过报告可能已有 minimal reproduction最小复现。开发新功能时可能需要新建一个项目充当测试套件——它还能兼作文档展示新功能预期如何工作。相关示例项目用示例项目中的相关示例验证。关于最小复现仓库内置的 info 插件可以帮你自动生成。按 info.md 在mkdocs.yml中启用plugins: - info后运行mkdocs build插件会把相关文件打包成example.zip并打印清单直接可附到 bug 报告中。其实现位于 src/plugins/info/plugin.py归档功能由 src/plugins/info/config.py 中的archive默认true与archive_stop_on_violation默认true两个开关控制打包完成后进程随即退出。创建复现的完整步骤升级到最新版、mkdocs new .引导项目、最小化配置、剔除所有非必要文件见 creating-a-reproduction.md。创建 Pull Request最初请以草稿draft形式创建 PR通过 GitHub 提供的各种界面完成即可——GitHub 已提供必要的信息此处不再赘述各界面操作。提交信息、错误与 squash提交信息要有意义让评审者以及未来的维护者能从提交信息看出这段变更做了什么、为什么做。提交粒度要细一次提交对应一件完整的小事方便逐段审查与回滚。合入时评审者可能squash你的多个提交并编辑提交信息——这是项目合入流程的一部分见上文时序图提交历史会在合入时被整理得更简洁。删除分支PR 合入 master 后应同时删除 Fork 上GitHub与本地 clone 中的分支避免对开发状态产生混淆。先切回 mastergit switch master git branch -d name后续 Pull Request后续 PR 必须从最新的 master 历史开始。一种简单做法是删除 Fork下次重新 Fork如果贡献频繁或连续做多个 PR也可以只做同步用 GitHub 界面同步 Fork 并 pull 到本地删除上次的 topic 分支本地与 Fork 都要再从主仓库的masterpull 到本地master然后开始新工作。应做与不应做不要不做任何解释就提交一个 PR。要先在讨论区说明你的意图让任何变更的理由在写代码之前就清晰。要在 PR 中链接相关的讨论或 issue提供上下文。要对任何不确定的事情提问。要扪心自问你的工作是否惠及更广泛的社区、让 Material for MkDocs 变得更好。要权衡变更的成本与收益有些看似合理的变更会引入较多复杂度却收益有限可能破坏既有行为或在后续其他变更时变得脆弱。要频繁合并并发变更把难以解决的冲突风险降到最低。仓库内可继续深挖的线索贡献流程总览与各类模板contributing/index.md、CONTRIBUTING.md提交 PR 前的开发环境、构建与自检命令customization.md、package.json生成最小复现的 info 插件实现src/plugins/info/plugin.py、src/plugins/info/config.py、info.md主题真实源码位置src/templates 与 src/plugins注意material目录为构建产物。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考