一、前言1.1 规范目的随着团队规模扩大与多角色协同开发场景增多代码仓库的版本管理、分支协作及质量管控面临诸多挑战如直接向主仓库推送代码导致的版本冲突、提交记录混乱、代码质量不可控等问题。为解决上述痛点本规范明确了基于 GitHub Organization组织的标准化代码协作流程核心确立“fork-sync-dev-pr-merge-sync”的闭环协作模式禁止任何形式直接向主仓库分支推送代码的操作。本规范的制定旨在实现以下目标一是保障主仓库代码的稳定性与可追溯性确保核心代码库不受非规范操作影响二是明确开发人员的协作职责与操作边界降低跨角色协作的沟通成本三是通过标准化流程提升代码评审效率强化代码质量管控四是形成可复用、可传承的协作机制为新成员快速融入团队提供清晰指引最终提升整体开发效率与交付质量。1.2 适用范围本规范适用于FreakStudioCNGitHub Organization以下简称Org下所有代码仓库的开发协作活动覆盖参与代码开发、评审、合并及维护的所有角色包括但不限于前端开发工程师、后端开发工程师、测试工程师、技术负责人及项目管理者。**无论开发任务类型如功能开发、Bug 修复、性能优化、文档更新等均需严格遵循本规范中的流程要求。对于紧急线上故障修复等特殊场景如需简化流程需经对应仓库技术负责人审批并在问题解决后补充完善相关操作记录确保流程追溯性。**本规范内容将根据GitHub功能更新及团队协作需求变化由技术管理小组定期修订并同步至全体相关人员。二、基础概念定义2.1 GitHub OrganizationOrgGitHub Organization中文常称“GitHub组织”是GitHub平台提供的团队级代码管理载体用于集中管理团队所有代码仓库、成员权限及协作配置。相较于个人GitHub账号Org 具备更精细的权限管控能力可通过“团队Team”分组实现成员权限的批量分配与管理确保不同角色仅能访问其职责范围内的仓库资源。本规范中提及的“主仓库”均隶属于该Org是团队代码的官方核心载体其代码版本代表项目的正式状态所有开发成果需通过规范流程合并至主仓库禁止任何未经审批的直接修改操作。2.2 Fork 仓库Fork是GitHub提供的仓库复制功能指将Org下的主仓库完整复制一份至个人GitHub账号下形成“个人Fork仓库”。Fork 仓库与主仓库独立存在开发人员拥有个人 Fork 仓库的完全操作权限包括推送代码、创建分支等但对主仓库仅拥有​只读​权限可​克隆​**、拉取更新不可直接推送。**Fork仓库的核心价值在于为开发人员提供安全的“试验场”既避免直接操作主仓库带来的风险又能通过后续的Pull Request机制实现代码的可控提交与评审。开发人员的所有代码开发工作需在个人​**Fork​仓库中完成而非直接在主仓库的分支上进行。**2.3 开发分支Dev Branch开发分支是指开发人员为完成特定开发任务如功能模块开发、Bug 修复在个人Fork仓库中基于主仓库的基准分支通常为main或master分支以下统称“主分支”创建的专用分支命名需遵循“任务类型-任务 ID-功能描述”的规范如“feat-T123-user-login”“fix-T456-payment-error”。​开发分支的作用是实现开发任务的隔离确保不同开发任务的代码修改互不干扰同时便于后续代码评审与问题定位。​每个开发任务应对应一个独立的开发分支任务完成后通过Pull Request合并至主仓库的对应分支合并完成后该开发分支可进行删除避免分支冗余。2.4 Pull RequestPRPull Request中文常称“合并请求”简称“PR”是GitHub平台提供的代码协作核心功能指开发人员在个人Fork​仓库的开发分支完成代码修改后向Org​主仓库的维护者发起的、请求将其开发分支的代码合并至主仓库目标分支的申请。PR不仅是代码合并的“入口”更是代码评审的核心载体。发起PR后主仓库的技术负责人需组织相关人员对PR中的代码进行评审检查代码质量、功能完整性、逻辑合理性及是否符合团队编码规范。只有通过所有评审环节的​**PR​才能被合并至主仓库的目标分支评审未通过的​PR​开发人员需根据评审意见在个人​Fork​仓库的开发分支中进行修改并同步更新​PR​内容。**2.5 Squash and Merge提交压缩合并Squash and Merge中文常称“提交压缩合并”是GitHub提供的一种PR合并方式指在将开发分支的代码合并至主仓库目标分支时将该开发分支上的所有零散提交记录如“修改 1”“优化 2”“修复 Bug”等压缩为一个完整、清晰的提交记录再合并至主仓库。该合并方式的核心优势在于保持主仓库主分支提交历史的简洁性与可读性使每个提交记录都对应一个完整的开发任务或功能点便于后续版本回溯、问题定位及发布日志编写。本规范要求所有​**PR​的合并必须采用“​Squash and Merge​”方式禁止使用“​Create a merge commit​”保留所有提交记录或“​Rebase and merge​”变基合并方式确保主仓库主分支的提交历史清晰可控。**三、核心开发流程总览本规范核心遵循​**“fork→ 同步 → 开发 → 提PR​​→ 合并 → 同步”​的闭环协作模式该模式从权限隔离、代码流转、质量管控三个维度保障主仓库代码安全同时兼顾开发效率。​整个流程以“个人 Fork 仓库为开发载体、PR 为协作枢纽、主仓库为成果归集核心”**​具体循环逻辑如下初始化阶段开发人员将Org主仓库Fork至个人账号完成个人Fork仓库与主仓库的关联基于主仓库主分支在个人Fork仓库创建专属开发分支搭建本地开发环境开发阶段开发前先同步主仓库最新代码至个人Fork仓库及本地开发分支避免基于旧版本开发导致冲突在本地开发分支完成代码编写、测试后推送至个人Fork仓库对应分支协作阶段基于个人Fork仓库的开发分支向主仓库目标分支发起PR经评审通过后采用“Squash and Merge”方式合并至主仓库同步阶段PR合并完成后及时将主仓库的更新同步至个人Fork仓库为下一次开发任务做好准备形成完整闭环。该流程的核心约束为“禁止直接向主仓库推送代码”所有代码变更必须通过**“个人 Fork 仓库 →PR​​评审 → 主仓库合并”​**的路径实现确保每一次代码变更都经过规范的质量校验。详细说明可看链接https://f1829ryac0m.feishu.cn/wiki/PEnKwQjCIi9Wi4kszmrcZhsunte?fromfrom_copylink