从Fork到Merge：使用Git+VSCode参与office-docs-powershell文档共建的进阶工作流

从Fork到Merge：使用Git+VSCode参与office-docs-powershell文档共建的进阶工作流

【免费下载链接】office-docs-powershellPowerShell Reference for Office Products - Short URL: aka.ms/office-powershell项目地址: https://gitcode.com/gh_mirrors/of/office-docs-powershell

office-docs-powershell 是 Office 产品（Teams、Exchange、Skype、Whiteboard 等）PowerShell Cmdlet 参考文档的官方仓库，内容最终会发布到微软技术站点，并直接服务于命令行中的Get-Help帮助系统。对于经常参与文档贡献的协作者来说，网页端编辑已无法满足需求——使用Git + VSCode 的本地工作流，从 Fork 到 Merge 的完整链路能让你批量编辑、本地校验、多机协作，是参与 office-docs-powershell 文档共建的进阶方式 🚀

为什么选择 Git + VSCode 进阶工作流？

网页端只需点击“Edit this file”即可提交小改动，但当你需要用 repo_docs/NEW_CMDLETS.md 中的流程批量生成并撰写 Cmdlet 文档时，本地 Git 工作流才是正解。

第 1 步：一键 Fork 仓库到你的账号

打开仓库页面，点击右上角的Fork按钮，仓库的完整副本就会出现在你的账号下——主仓库即“上游（Upstream）”，你的副本即“下游（Fork）”。

Fork 完成后，可通过右上角头像菜单进入Your profile → Repositories，确认你的 Fork 已列出。建议定期将 Fork 与上游同步，避免长期脱节。

第 2 步：克隆 Fork 到本地开发机

在 VSCode 中按 `Ctrl + `` 打开内置终端（Git Bash），克隆你 Fork 的仓库：

git clone https://gitcode.com/gh_mirrors/of/office-docs-powershell

💡 克隆的是你自己的 Fork（URL 中包含你的账号），而不是上游主仓库。

三端协作关系如下图所示：本地仓库 ↔ 你的 Fork ↔ 上游主仓库。

第 3 步：配置 upstream 远程，保持 Fork 同步

添加上游远程并拉取最新内容，这一步是让后续合并不冲突的关键：

git remote add upstream https://gitcode.com/gh_mirrors/of/office-docs-powershell git fetch upstream

第 4 步：创建工作分支，隔离每次改动

为每个改动任务创建独立分支，-b参数会在创建的同时切换过去：

git checkout -b fix-get-mailbox-docs

第 5 步：用 VSCode 编辑 PowerShell Cmdlet Markdown

• 分屏预览：VSCode 右上角的侧边预览图标可让 Markdown 源码与渲染效果并排显示，所见即所得 📝
• 遵循 platyPS schema：Cmdlet 参考文档的标题结构有严格约定，任何偏差都会导致 PR 校验失败或Get-Help报错
• 每句一行：Git 按行比对差异，每个句子或概念单独占一行，段落间空一行
• 善用现有内容：大量参数描述在各 Cmdlet 间通用，参照同产品的既有文档撰写即可

各产品线文档的存放位置速查：

新增 Cmdlet 文档时，仓库提供了自动化工具：用 platyPS 的New-MarkdownHelp从 PowerShell 会话导出 Markdown 骨架，再手动补全描述。详细步骤见仓库内的 repo_docs/NEW_CMDLETS.md 和 repo_docs/UPDATE_CMDLETS.md。

第 6 步：提交并推送到你的 Fork

git add . git commit -m "更新 Get-Mailbox 文档：补充新参数说明" git push origin fix-get-mailbox-docs

第 7 步：合并上游 master，提前化解冲突

提交 Pull Request 前，先切回工作分支合并上游主分支。注意方向：把上游 master 合并进你的分支，而不是反过来，这样上游维护者合并时才会顺畅：

git fetch upstream git merge upstream/master

如有冲突，在 VSCode 中直接处理，解决后再次推送即可。

第 8 步：创建 Pull Request，等待审核合并

回到仓库页面，点击New Pull Request→ 选择compare across forks→ 选定上游分支与你的工作分支 → 填写标题与描述（可 @ 提醒评审人）→ 点击Create pull request。

首次提交时，CLA 机器人会自动检查贡献者许可协议，按提示完成一次即可。维护者审核通过后，PR 被 Merge 进 master，你的内容随后发布上线——用户执行Get-Help <Cmdlet>时看到的，正是你写下的文字 🎉

成果验证与更多贡献资源

• 合并发布后，Cmdlet 文档会出现在官方文档站点，并同步到 PowerShell 的Get-Help在线帮助
• 完整进阶流程原文：repo_docs/ADVANCED.md
• 新增 / 更新 Cmdlet 文档指南：repo_docs/NEW_CMDLETS.md、repo_docs/UPDATE_CMDLETS.md
• 常见问题解答：repo_docs/FAQ.md
• 各文档负责人信息：ContentOwners.txt
• 文档自动化工具（Cmdlet 文档更新器）：tools/office-cmdlet-updater/
• 项目遵循微软开源行为准则，贡献前请阅读根目录的 LICENSE 与 SECURITY.md

至此，你已经掌握了从 Fork 到 Merge 的完整闭环：Fork → Clone → 建分支 → 编辑校验 → 推送 → 合并上游 → Pull Request → 发布。祝你的第一篇文档顺利合入！

【免费下载链接】office-docs-powershellPowerShell Reference for Office Products - Short URL: aka.ms/office-powershell项目地址: https://gitcode.com/gh_mirrors/of/office-docs-powershell