OpenProject 内部文档贡献流程指南基于 GitHub Desktop 的分支、提交与 Pull Request 协作规范【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject本篇指南面向拥有 OpenProject 仓库写权限的内部团队成员系统讲解如何以 GitHub Desktop 加 Typora 的组合完成克隆仓库 → 拉取更新 → 新建分支 → 修改文档 → 提交推送 → 创建 Pull Request → 请求评审的完整文档贡献闭环。读完本文你将掌握与 OpenProject 官方文档团队opf/doc-writers一致的协作惯例能够规范、高效地将文档改动合入release分支并了解法律文档等特殊场景的处理规则。面向读者谁适合这份指南OpenProject 的文档贡献流程根据贡献者权限分为两条路径内部贡献者本文主题拥有 OpenProject 仓库 写权限的团队成员可以直接克隆主仓库并在其上创建分支、推送改动。外部贡献者没有写权限的社区用户需要先 Fork 仓库再通过 Pull Request 把改动合并回上游。完整流程见 文档贡献流程外部贡献者。两条路径的最终目标一致——通过 Pull Request 将文档改动合入最新 release 分支例如release/16.0区别仅在于内部成员省去了 Fork、禁用 GitHub Actions、切换默认分支、同步 Fork 等中间环节。前置条件开始之前请确认以下条件已经满足GitHub 账号贡献者需要拥有一个 GitHub.com 账号账号创建步骤见 外部贡献者流程中的 Step 1。仓库写权限贡献者拥有 OpenProject 仓库opf/openproject的写权限这是内部流程与外部流程的根本区别。Typora 编辑器用于编辑 Markdown 文档安装说明见 外部贡献者流程中的 Step 2。GitHub Desktop以图形界面替代命令行完成 Git 操作安装说明见 外部贡献者流程中的 Step 3。Note: OpenProject 文档全部使用 Markdown 编写Typora 让作者可以专注于内容而非格式GitHub Desktop 则让不熟悉命令行的贡献者也能轻松完成 Git 协作。工具的详细作用对比参见 文档贡献流程。全流程速览步骤操作关键要点第 1 步Clone 主仓库File - Clone repository选择opf/openproject第 2 步Fetch origin每次改动前必须先更新本地仓库第 3 步新建分支基于最新 release 分支创建分支名描述改动内容第 4 步Typora 打开文件通过File - Open定位本地仓库目录第 5 步修改并保存聚焦内容修改后务必保存第 6 步Commit提交信息要能帮助他人理解改动第 7 步Push origin将本地改动上传到 GitHub.com第 8 步创建 Pull Request选择 base 分支与目标分支填写描述第 9 步请求评审添加documentation标签指定opf/doc-writers第 10 步等待反馈评审通过LGTM后合入分步详解第 1 步在 GitHub Desktop 中克隆 OpenProject 仓库在进行任何修改之前需要先在本地计算机上创建 OpenProject 仓库的克隆。打开 GitHub Desktop导航到File - Clone repository。在弹出的窗口中选择仓库opf/openproject同时在计算机上为克隆的仓库选择一个存放目录点击Clone完成克隆。第 2 步更新本地仓库Fetch originImportant: 在做出任何修改之前务必先更新本地仓库。在主工具栏中选择你要在其上工作的分支例如release/16.0。点击主工具栏中的Fetch origin按钮拉取远程最新提交。这一步确保你的本地分支与远程保持同步避免基于过期内容进行修改。若本地分支长期未更新改动可能落后于在线文档并引发冲突。第 3 步为你的修改创建新分支在下拉菜单中选择最新 release 分支例如release/16.0作为当前分支。在同一个下拉菜单中点击New branch。在弹出的窗口中输入一个能描述你改动内容的分支名同时选择要基于的分支例如release/16.0点击Create branch。为每个改动单独创建分支可以让 Pull Request 的评审对象清晰聚焦也便于并行推进多项文档任务。第 4 步在 Typora 中打开待修改的文件在 Typora 中通过File - Open打开你要修改的文件。在文件选择器中导航到第 1 步中选择的本地克隆目录选中目标 Markdown 文件即可。第 5 步在 Typora 中修改并保存文件Typora 让文档修改变得非常简单——所见即所得。完成修改后不要忘记保存Ctrl/Cmd S未保存的改动不会出现在 GitHub Desktop 的变更列表中。第 6 步提交到本地仓库Commit打开 GitHub Desktop在这里可以看到你在本地仓库中做出的所有修改。填写一条最能描述你改动的提交信息commit message。这条描述应当让其他用户能够轻松理解你做了什么例如概括修改的文档主题与变更要点。第 7 步推送你的改动到 GitHub.com此时改动还只存在于本地仓库。要让它出现在 GitHub.com 上需要点击Push origin按钮将改动上传推送到远程。第 8 步创建 Pull RequestPull Request 是向 OpenProject 团队请求评审的工作流。通过 Pull Request你实际上是请团队成员检查你的改动并将其合并到你希望合入的目标分支例如release/16.0。在把本地改动推送到远程后点击Create Pull Request按钮。浏览器会打开对比页面第一个下拉框base选择你希望改动被合入的分支例如release/16.0。第二个下拉框compare选择你在第 3 步创建、包含你改动的分支。在 Pull Request 的描述字段中为你的改动输入一段摘要。如果 community.openproject.org 上已有对应的工作包work package也可以将其添加到描述中——这会在你的 Pull Request 与工作包之间建立关联方便团队追踪文档需求与实现。第 9 步请求评审为 Pull Request 选择documentation标签。在Reviewers字段中选择opf/doc-writers。documentation标签与opf/doc-writers评审组是 OpenProject 文档协作的固定惯例外部贡献者流程中的 Step 16 也遵循同样的约定参见 文档贡献流程。第 10 步等待评审反馈等待评审者反馈希望一切顺利——LGTM 意为 Looks good to me(rge)。恭喜你完成了对 OpenProject 文档的第一次贡献。团队非常感激你的付出。内部流程与外部流程的差异对照对比 外部贡献者流程 可以发现内部流程省略了以下环节环节外部贡献者内部贡献者Fork 仓库需要获得自己仓库的写权限不需要直接拥有主仓库写权限禁用 GitHub Actions需要避免不必要的自动化任务不需要切换 Fork 默认分支需要切到 release 分支不需要同步 Fork / 拉取上游每次编辑前需要只需 Fetch origin克隆对象自己的 Forkopf/openproject主仓库推送目标自己的 Fork主仓库有写权限两者的评审环节完全一致都要打上documentation标签、指派opf/doc-writers评审并等待 LGTM 后合入。仓库侧的事实依据与写作规范文档仓库的组织方式OpenProject 的文档源码就存放在本仓库的docs/目录下按主题划分为user-guide/、system-admin-guide/、installation-and-operations/、api/、development/、release-notes/、enterprise-guide/等顶层目录完整目录清单参见 docs/ 与 文档风格指南 中的目录内容表。每个文档主题对应一个子目录其中必须包含一个README.md作为该页面的正文文件。从本仓库的文档文件例如本文所在的 内部贡献者指南可以看到每个文档页面顶部都带有一段 YAML front mattersidebar_navigation: title: Internal docs contributor priority: 800 description: Quick guide for internal team members that have write permissions keywords: contribution, documentation, documentation processsidebar_navigation.title控制侧边栏显示名称priority控制该页面在菜单中的排序权重description与keywords用于页面元信息与检索。贡献者在新建文档页时应当遵循 文档风格指南 中规定的目录与文件命名规则新主题使用小写目录名加README.md多词名称用连字符-或下划线_连接不使用特殊字符、空格、大写字母。风格指南还强调单一事实来源single source of truth——不要在多个位置重复同一信息而是用相对链接指向已有内容。版本分支与当前仓库状态原文档以release/16.0作为最新 release 分支的示例。需要说明的是该示例分支仅存在于opf/openproject软件仓库中见下文法律文档说明实际贡献时应以当前最新的 release 分支为准。从本仓库源码看当前主分支为dev版本号定义在 lib/open_project/version.rb 中MAJOR 18、MINOR 0、PATCH 0即当前开发版本为 18.0.0——贡献者应据此判断哪个 release 分支是最新的。关于法律文档Legal docs的额外说明文档贡献流程中有一个特例场景法律文档存放于独立的opf/legal仓库其协作规则与主仓库文档不同部署机制main分支始终部署在官方网站的法律页面上该部署需要由市场团队手动触发不会自动发布。轻微修改如果只是微小的改动不需要评审可以直接在main分支上完成修改无需创建新分支和 Pull Request。需要评审的改动如果需要评审则必须从main分支创建一个新分支来提交改动。分支归属release/16.0这样的分支只存在于opf/openprojectOpenProject 软件仓库中法律文档仓库中没有该分支不要混淆两者的分支体系。遇到问题怎么办支持渠道如果在贡献过程中遇到疑问或问题可以通过社区平台开立工单ticket获取支持详细步骤见 贡献支持指南在 OpenProject 社区平台登录或注册账号注册需要先发送主题为 Joining community 的邮件申请邀请。新建一个类型为文档Documentation的工作包。填写明确的标题。详细描述你遇到的问题以及希望得到的帮助。可选附上截图或日志文件。点击Save保存。团队会通过工单与你取得联系。延伸阅读文档贡献流程外部贡献者完整版含工具安装、Fork、同步、重建分支等完整细节文档风格指南命名规则、Markdown 规范、截图要求、告警框格式贡献支持开立工单获取帮助文档贡献总览文档贡献的入口与三种反馈渠道邮件、社区工作包、Pull Request贡献指南总览翻译、回馈社区等其他贡献方式OpenProject 版本定义确认当前版本号与 release 分支对应的依据/DSMLparameter /DSMLinvoke /DSMLtool_calls【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考