OI Wiki 编写与协作贡献指南从 GitHub 网页编辑到本地 Git 工作流【免费下载链接】OI-wiki:star2: Wiki of OI / ICPC for everyone. 某大型游戏线上攻略内含炫酷算术魔法项目地址: https://gitcode.com/GitHub_Trending/oi/OI-wikiOI Wiki是一个免费开放、持续更新的编程竞赛OI / ICPC知识整合站点其全部内容以 Markdown 文档形式维护在公开仓库中并依赖社区贡献者协作完善。本文基于仓库中的「如何参与」文档docs/intro/htc.md系统梳理参与OI Wiki编写的完整流程包括在 GitHub 网页端编辑单个或多个页面、向 Pull Request 追加更改、使用 Git 在本地编辑、在 Netlify 预览构建结果以及修改目录、author 字段、重定向文件时的注意事项和 commit / PR 信息规范。阅读本文后你将能够按照项目约定提交一份符合社区标准、可顺利合并的内容贡献。贡献前的准备贡献指南与项目方针在动手编辑任何页面之前请先阅读两份纲领性文件以更好地与社区贡献者合作、交流OI Wiki 贡献指南说明项目的协作规范与社区期待。项目方针见 docs/intro/about.md 一节的「OI Wiki 不是什么」等条目帮助理解项目的内容边界与定位。? 在开始编写一段内容之前请先查阅 Issues确认没有别人在做相同的工作之后再开一个新 issue 记录待编写的内容避免重复劳动。Issues 中也有很多待修复/解决的问题尤其是项目的迭代计划Iteration Plan从这里获取任务是一个很好的开始。为保证条目内容的专业性和准确性编辑前建议考虑以下几点选择熟悉的领域优先编辑与你的专业知识、学习背景或兴趣爱好相关的条目这有助于创作出高质量内容。谨慎对待新领域如果对某个主题还处于初学阶段建议先通过阅读、学习加深理解有一定把握后再动手编辑。查阅相关资料为条目添加或修订内容时建议先查阅权威文献和资料确保信息准确无误也欢迎在页面评论区或社区中与其他编者交流讨论。正如维基百科所言不要害怕编辑勇于更新页面在 GitHub 网页端编辑即使对 Git 一无所知也能完成出色的贡献。在 GitHub 上编辑页面参与OI Wiki编写需要一个 GitHub 账号但不需要高超的 GitHub 技巧。所有修改在被合并进主仓库之前均不会出现在OI Wiki主站上因此无需担心破坏正在显示的内容。编辑单个页面内的内容在OI Wiki网站上找到对应页面点击正文右上方目录左侧的「编辑此页」按钮编辑图标确认已阅读本文和 格式手册 后点击按钮跳转到 GitHub 进行编辑在编辑框内编写想修改的内容。注意在修改和提交过程中请关闭自动翻译软件它可能产生不必要的麻烦例如将你修改的文件错误改名从而影响目录结构编写完成后滚动到页面下方按照下文「commit 信息格式规范」填写 commit 信息点击Propose changes提交修改。GitHub 会自动创建一份OI Wiki仓库的分支并把提交添加到该分支GitHub 跳转到你的分支仓库页面后页面上方会显示绿色的Create pull request按钮点击后进入创建 Pull Request 页面。向下滚动检查修改无误按「Pull Request 信息格式规范」书写 PR 信息再点击绿色的Create pull request按钮至此 Pull Request 便提交到了仓库等待管理员审核并合并即可。在等待合并期间你可以给他人的 Pull Request 提意见、点赞或点踩。若有新消息会在网页右上角出现提示并附邮件提醒取决于个人设置中配置的通知方式。编辑多个页面内的内容如果需要同时编辑互无关联的多个页面可以进入 GitHub 网页版 VS Code 编辑器批量修改打开 OI-Wiki/OI-Wiki 仓库按下键盘上的.键或者把 URL 中的github.com更改为github.dev进入 GitHub 网页版 VS Code 编辑器在编辑器中作出对页面源文件的更改可用右上角的预览按钮或CtrlKV快捷键在右侧打开预览界面修改完成后使用左侧的 Source Control 选项卡按照「commit 信息格式规范」填写 commit 信息并提交提交时会提示是否创建该仓库的分支点击绿色的Fork Repository按钮即可提交后网页上方中央会弹出提示框第一个提示框填写标题第二个提示框填写此提交要提交到的仓库内分支名称之后右下角会弹出形如Created Pull Request #1 for OI-Wiki/OI-Wiki.的提示点击蓝字链接即可查看该 Pull Request。向 Pull Request 追加更改当 reviewer 提出修改意见后需要向已有 PR 追加新的提交打开 OI-Wiki 的 Pull Request 列表找到你提交的 PR 并点击PR 标题下方会有一段形如你的ID wants to merge x commits into OI-wiki:master from 你的ID:patch-1的文字点击你的ID:patch-1部分你会被重定向到自己的分支仓库文件列表左上角的分支名称即提交 PR 的分支示例中为patch-1进行需要的更改单个文件或多个互无关联的页面直接找到文件修改滚动到页面下方按规范填写 commit 信息后点击Commit changes多个文件按.键或把github.com改为github.dev进入网页版 VS Code 编辑器修改然后在 Source Control 选项卡中按规范提交这些更改会被自动追加进你的 Pull Request 中。使用 Git 在本地进行编辑? 对一般用户项目更推荐使用上文所述的 GitHub 网页编辑器。但对于一些特殊场景如需要使用 GPG 签名更推荐用 Git 在本地编辑。本地编辑的流程与标准 GitHub 协作模式一致将主仓库 Fork 到自己的账户中将 Fork 后的分支仓库克隆clone到本地在本地修改后提交commit这些更改将这些更改推送push到克隆下来的分支仓库向主仓库提交 Pull Request。详细的操作方式可参考仓库中的 Git 入门文档。若需向已有 PR 追加更改只需在 clone 下来的本地分支仓库中继续修改并 commit、push更改同样会自动追加到 PR 中。在构建的网页中预览变更每个 Pull Request 页面下方都可以找到测试与预览入口。点击netlify/oi-wiki/deploy-preview一项的 Details 链接即可进入由该 PR 的变更内容自动构建出的预览站点方便在合并前核对渲染效果这项预览能力来自仓库的 Netlify 集成配置见 netlify.toml 与 Dockerfile站点使用 MkDocs 构建页面导航结构由 mkdocs.yml 定义。目录导航与引用的变更如果需要添加一个新页面或者修改已有页面在目录中的链接就需要对仓库根目录的mkdocs.yml文件作出改动——它集中定义了站点导航nav结构与每个页面在目录中的位置例如「如何参与」页面即注册在intro/htc.md这一项之下mkdocs.yml 第 21 行。添加新页面可以参考既有条目的格式。但除非是进行重构或修正名词否则不建议对既有页面的引用链接进行修改PR 中不必要的此类修改将被驳回。如果坚持修改链接请注意同步更新下述两处内容。author 字段GitHub API 在文件目录变更后无法跟踪统计贡献者因此项目在 Markdown 文件头部手动维护了一个作者列表。author 字段位于整个 Markdown 文件的开头形如author: Ir1d, cjsoft相邻两个 ID 之间用逗号加空格隔开。这里的 ID 是 GitHub 用户名即 GitHub profile 地址例如https://github.com/Ir1d中的Ir1d。修改链接时需要把当前页面中的 contributors 逐一填入 author 字段。重定向文件修改链接时为了避免站外引用出现死链还需要修改重定向文件docs/_redirects。该文件同时服务于两套用途生成 Netlify 的重定向配置生成用于站内跳转的静态 HTML 文件由构建脚本scripts/post-build/redirect/generate-redirects.py实现。文件每一行表示一条重定向规则分别写跳转的起点和终点 URL不包含域名格式如下/path/to/src /path/to/desc例如仓库当前的重定向记录中/intro/oi被重定向到/contest/oi、/intro/wsl被重定向到/tools/wsldocs/_redirects 第 1、10 行。需要注意所有跳转均为301 跳转只有在修改目录中 URL 造成死链时才需要修改此文件。从源码看生成逻辑位于 scripts/post-build/redirect/generate-redirects.py脚本逐行读取site/_redirects为每条规则在site目录下生成一个带canonical链接与http-equivrefresh的 HTML 跳转页同时输出 Nginx 跳转配置。配套的校验脚本 scripts/post-build/redirect/check-redirects.py 则会比对旧站与新建站点生成的 HTML 集合若新站点缺失旧站页面即_redirects未覆盖会提示Some pages are missing in new site, please update docs/_redirects并以非零码退出——这正是「更新链接必须同步维护重定向」这一约定在构建层的强制保障。Commit 信息格式规范每次提交时的 commit 信息需要遵守以下基本要求commit 摘要简要描述这一次 commit 改动的内容长度不要超过 50 字符超出的部分会自动置于正文中如需进一步描述本次 commit 内容请在正文中详细说明。commit 摘要推荐按如下格式书写修改类型(文件名): 修改的内容修改类型分为四类feat用于添加内容的情况fix用于修正现有内容错误的情况refactor用于对一个页面进行重构较大规模的更改的情况revert用于回退之前更改的情况。Pull Request 信息格式规范对于 Pull Request请遵守以下要求标题写明本次 PR 的目的——做了什么工作、修复了什么问题内容简要叙述修改内容。如果修复了某个 issue 的问题请在内容中添加fix #xxxx字段其中xxxx代表 issue 的编号仔细阅读贡献指南和社区公约在同意后勾选 PR 模板中的复选框表示同意以上指南和公约。PR 标题推荐使用如下格式修改类型(文件名): 修改的内容 (对应 issue 的编号)修改类型与 commit 规范一致feat/fix/refactor/revert。实际提交中可参考以下示例fix(ds/persistent-seg): 修改代码注释使描述更清晰fix: tools/judger/index 不在目录中 (#3709)feat(math/poly/fft): better proofrefactor(ds/stack): 整理页面内容协作流程从 PR 到正式发布一个内容贡献从提交到上线会经历如下完整的自动化协作流程收到新的 Pull Request 后GitHub 会给 reviewer 发送邮件通知与此同时在 GitHub Actions 和 Netlify 上会运行两组测试进度同步显示在 PR 页面下方GitHub Actions确认 PR 中内容的修改不会影响网站构建进程Netlify把 PR 中的更新构建出来方便 reviewer 审核测试完成后点击 Details 可进入预览见上文reviewer 可能会发现问题并提出review或suggested changes建议更改灰色图标/requested changes强制更改红色图标仅当 reviewer 拥有仓库写权限时出现。此时需要按上文「向 Pull Request 追加更改」的方法继续补充提交在足够多 reviewer 投票通过一个 PR 后PR 才可以合并到 master 分支合并到 master 分支后GitHub Actions 会重新构建网站内容并更新到 gh-pages 分支服务器拉取 gh-pages 分支的更新重新部署最新版本的内容。可见主分支合入 → Actions 重建 → gh-pages 更新 → 服务器拉取部署构成了一条完整的发布链路而贡献者的每一次修改都需要在提交前遵循 commit 与 PR 规范确保整条链路可追踪、可审查、可回滚。小结参与OI Wiki的编写并不需要高超的 Git 技巧从网页端「编辑此页」按钮的轻量修改到网页版 VS Code 的多文件批量编辑再到本地 Git 的完整协作流程项目为不同水平的贡献者都提供了清晰的路径。关键在于遵守项目约定——撰写前查阅贡献指南与格式手册修改链接时同步维护 mkdocs.yml 的导航、文件头 author 字段与 docs/_redirects 重定向规则并按照修改类型(文件名): 修改的内容的规范书写 commit 与 PR 信息。正如项目的文档所倡导的那样不要害怕编辑勇于更新页面。【免费下载链接】OI-wiki:star2: Wiki of OI / ICPC for everyone. 某大型游戏线上攻略内含炫酷算术魔法项目地址: https://gitcode.com/GitHub_Trending/oi/OI-wiki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考