程序代码管理规范

程序代码版本管理规范1.总则1.1目的为规范程序代码版本管理流程，解决开发过程中分支混乱、代码丢失、版本追溯困难、并行开发冲突等问题，保障主分支代码稳定可发布，提升团队协作效率，明确版本管理责任，确保代码迭代可追溯、可回滚，保护代码资产安全，特制定本规范。本规范适用于所有参与程序开发、测试、部署的相关人员，涵盖代码从开发、提交、评审到发布、维护的全生命周期。1.2核心目标主线稳定：确保主分支（Main/Master）代码随时可部署至生产环境，杜绝直接修改主分支导致的线上风险；并行开发：支持多开发人员同时开展不同功能开发，互不干扰，高效解决代码合并冲突；版本可追溯：所有代码变更均能定位修改人、修改时间、修改原因，出现问题可快速回滚至稳定版本；流程简化：规则简洁易懂、可落地，降低执行成本，避免过度复杂的流程影响开发效率。1.3适用范围本规范适用于公司所有研发项目（包括前端、后端、移动端等）的代码版本管理，涉及开发人员、测试人员、运维人员、项目负责人等所有相关角色，覆盖代码开发、提交、评审、合并、发布、热修复等全流程，无论采用Git、SVN等何种版本控制工具，均需遵循本规范核心要求。1.4核心原则原子性原则：每次代码提交仅完成一个独立功能开发或一个Bug修复，避免多个不相关修改合并提交，降低回滚风险；可追溯原则：提交注释、分支命名、版本号均需规范，清晰记录每一次变更的目的和内容，确保历史版本可查询、可追溯；权限分级原则：按角色分配代码仓库操作权限，禁止无权限操作，主分支需设置保护机制，杜绝直接推送；持续集成原则：功能分支提交后需通过自动化测试（CI），评审通过后方可合并，保障代码质量。2.版本控制工具规范2.1工具选择优先选用Git作为分布式版本控制工具，适用于多团队协作、离线开发、快速迭代的项目场景；对于传统企业、对权限控制要求严格（如医疗、金融等需严格审计）的项目，可选用SVN作为集中式版本控制工具。所有项目需统一版本控制工具，禁止混合使用多种工具，避免版本混乱。2.2工具配置统一配置用户信息：所有开发人员需在本地工具中配置统一格式的用户名（姓名拼音全拼）和公司邮箱，确保提交记录可精准关联责任人；配置钩子脚本：通过pre-commit钩子自动检查代码格式、消除冗余空行，通过post-commit钩子自动触发CI流程，减少人工校验成本；仓库备份：远程代码仓库需开启自动备份功能，定期（至少每周一次）备份代码及版本记录，防止代码丢失；本地仓库建议定期同步远程仓库，避免本地代码与远程脱节。3.分支管理规范采用“主分支+辅助分支”的分层管理策略，明确各分支的角色、用途和操作规范，避免分支冗余和混乱，适配90%以上的项目场景。3.1分支类型及用途分支类型命名规范用途操作禁忌主分支（长期存在）Main/Master存放经过充分测试、可直接部署至生产环境的稳定代码，与生产环境运行代码完全一致，作为版本追溯的基准。严禁直接推送代码、直接修改；唯一代码来源是合并请求，需经过评审和CI检查。开发分支（长期存在）Develop作为新功能集成的核心分支，存放下一个版本的预览代码，所有功能开发完成后均合并至此，用于后续测试和集成。禁止直接从该分支部署至生产环境；禁止未经评审的代码合并。功能分支（临时存在）feature/功能描述（小写英文，用连字符连接），例：feature/user-payment、feature/login-optimize从Develop分支拉取，用于单个功能开发或非紧急Bug修复，一个分支对应一个功能/修复任务。生命周期需简短，完成开发并合并后立即删除；禁止直接合并至Main分支。发布分支（临时存在）release/版本号，例：release/v1.2.0从Develop分支拉取，用于版本发布前的最终测试和Bug修复，隔离发布流程与开发流程。禁止新增功能，仅允许修复测试发现的Bug；完成发布后立即删除。热修复分支（临时存在）hotfix/问题描述，例：hotfix/critical-payment-bug、hotfix/v1.2.1从Main分支最新稳定标签拉取，用于紧急修复生产环境出现的Bug，快速响应线上问题。仅用于紧急修复，不允许新增功能；修复完成后需同时合并至Main和Develop分支，合并后立即删除。3.2分支操作流程3.2.1功能开发流程拉取最新代码：从Develop分支拉取最新代码，确保本地分支与远程Develop分支同步；创建功能分支：基于最新的Develop分支，创建功能分支，命名遵循功能分支规范；本地开发：在功能分支上专注开发，频繁提交代码（建议每天至少提交1次），避免代码丢失；提交与自测：完成开发后，本地跑通单元测试和基本功能验证，确保代码可正常运行；发起合并请求：向Develop分支发起合并请求（PR/MR），并@相关同事进行代码评审；评审与测试：评审通过且CI自动化测试（编译、单元测试、代码风格检查）通过后，方可合并；分支清理：合并成功后，立即删除该功能分支，保持仓库整洁。3.2.2版本发布流程创建发布分支：当Develop分支集成足够功能，具备发布条件时，从Develop分支拉取发布分支，命名遵循发布分支规范；测试与修复：QA团队仅测试发布分支，发现的Bug在该分支上直接修复，不新增任何功能；合并至主分支：测试通过后，将发布分支合并至Main分支，并在Main分支上打对应版本标签（Tag），标签名与发布分支版本号一致；同步至开发分支：将发布分支合并回Develop分支，确保发布分支上的Bug修复同步到后续开发中；部署与清理：将Main分支上打标签的代码部署至生产环境，部署完成后删除发布分支。3.2.3线上紧急Bug修复流程创建热修复分支：从Main分支最新稳定标签拉取热修复分支，命名遵循热修复分支规范；快速修复与自测：在热修复分支上快速修复Bug，完成后本地自测，确保修复有效；合并至主分支：将热修复分支合并至Main分支，打上新的版本标签（补丁版本号升级）；同步至开发分支：将热修复分支合并回Develop分支，避免后续开发遗漏该Bug修复；紧急部署与清理：将新标签对应的代码部署至生产环境，解决线上问题，部署完成后删除热修复分支。4.代码提交规范4.1提交前提提交前必须本地自测，确保代码可正常编译、运行，无语法错误、逻辑错误；提交前需拉取远程对应分支最新代码，解决所有合并冲突，避免冲突遗留至远程仓库；仅提交与当前开发任务相关的代码，禁止提交无关文件（如本地配置文件、日志文件、编译产物等），可通过.gitignore文件过滤无关文件。4.2提交注释规范提交注释需清晰、简洁、具体，明确说明“做了什么”“为什么做”，禁止模糊描述（如“更新代码”“修Bug”），统一格式为：（变更类型）描述内容（关联任务号/需求号）4.2.1变更类型feat：新功能开发（例：feat：新增用户支付功能（任务123））；fix：Bug修复（例：fix：解决登录接口超时问题（需求456））；docs：文档更新（例：docs：完善接口文档（文档789））；style：代码格式调整（不影响代码逻辑，如缩进、空格、注释修改）；refactor：代码重构（不新增功能、不修复Bug，仅优化代码结构）；test：新增/修改测试用例；chore：构建流程、依赖包更新等辅助操作。4.2.2注释要求描述内容需简洁明了，不超过50字，核心信息突出；必须关联任务号、需求号或Bug编号，便于追溯关联需求；若修改内容复杂，可在注释后添加换行，补充详细说明（如修改原因、涉及模块等）。4.3提交频率建议每天至少提交1次代码，每次提交对应一个小的功能节点或Bug修复，避免长时间不提交导致代码丢失或合并冲突难以解决；禁止一次性提交大量无关修改，确保每次提交的原子性。5.版本号规范5.1版本号格式采用“主版本号.次版本号.修订号”三级格式，即：X.Y.Z，其中X、Y、Z均为非负整数，从0开始递增，具体规则如下：主版本号（X）：当代码发生重大变更（如核心架构调整、功能重构、不兼容的API变更）时升级，初始值为1.0.0；次版本号（Y）：当新增功能、优化现有功能（不破坏原有兼容性）时升级，初始值为0，每次升级后Z重置为0；修订号（Z）：当修复Bug、调整代码格式、优化性能（不新增功能、不破坏兼容性）时升级，初始值为0。5.2版本号使用规范版本号需连续递增，禁止跳跃、重复或随意修改，如1.0.0→1.0.1→1.1.0→1.1.1，禁止出现1.0.0→1.2.0的跳跃；Main分支上的每个稳定版本必须对应唯一的版本标签（Tag），标签名格式为“v+版本号”，例：v1.2.0、v1.2.1；发布分支、热修复分支的命名需包含版本号，与Main分支标签版本号保持一致；版本变更后，需在项目文档（如CHANGELOG.md）中记录版本号、变更日期、变更内容、责任人等信息，确保版本追溯。6.代码评审规范6.1评审范围所有合并至Develop、Main、release分支的代码，均需经过代码评审，禁止未经评审直接合并；功能分支合并至Develop分支需至少1名同事评审，release分支、hotfix分支合并至Main分支需至少2名同事评审（含项目负责人）。6.2评审内容代码逻辑：逻辑是否清晰、合理，是否符合业务需求，有无潜在Bug；代码质量：代码风格是否统一，是否存在冗余代码、重复代码，命名是否规范；测试覆盖：是否编写对应的测试用例，测试用例是否覆盖核心逻辑；兼容性：是否考虑不同环境、不同版本的兼容性，有无破坏原有功能；安全性：是否存在安全隐患（如SQL注入、XSS攻击、权限泄露等）。6.3评审流程发起评审：开发人员完成功能开发并提交合并请求后，@相关评审人员（如项目负责人、同模块开发人员），说明修改内容和重点关注项；评审执行：评审人员需在24小时内完成评审，对存在问题的代码提出具体修改意见，标注“需要修改”；对无问题的代码标注“评审通过”；修改重审：开发人员根据评审意见修改代码后，重新提交合并请求，再次发起评审，直至评审通过；评审归档：评审通过后，评审人员需在合并请求中确认，合并完成后，相关评审记录需留存，便于后续追溯。7.代码回滚规范7.1回滚场景合并至Develop分支后，发现代码存在严重逻辑错误、无法正常运行，影响后续开发；合并至Main分支后，部署到生产环境发现重大Bug，无法快速修复，需紧急回滚至稳定版本；代码提交错误（如提交了无关代码、合并了错误分支）。7.2回滚流程发起回滚申请：由开发人员或项目负责人发起回滚申请，说明回滚原因、回滚目标版本（需明确版本标签或提交ID）；回滚审批：对于回滚至Main分支（生产环境）的申请，需经项目负责人、运维人员共同审批；回滚至Develop分支的申请，需经项目负责人审批；执行回滚：审批通过后，由指定人员执行回滚操作，回滚后需本地测试，确保回滚版本可正常运行；同步通知：回滚完成后，需在团队群同步回滚信息（包括回滚版本、回滚原因、影响范围），确保所有相关人员知晓；记录归档：将回滚操作、回滚原因、审批记录、测试结果等信息留存归档，便于后续追溯。7.3注意事项回滚前需备份当前版本代码，避免回滚操作导致代码丢失；回滚至生产环境后，需立即暂停该版本的后续部署，排查问题原因，修复后重新发布；禁止未经审批擅自执行回滚操作，尤其是生产环境的回滚，避免造成业务中断。8.责任与监督8.1角色责任开发人员：严格遵循本规范进行代码开发、提交、分支操作，确保提交代码质量，配合代码评审，及时修改评审意见；测试人员：在测试过程中关注版本分支的正确性，及时反馈测试中发现的Bug，配合版本发布和回滚测试；项目负责人：负责监督本规范的执行，审批合并请求、回滚申请，协调解决版本管理中的冲突和问题，确保版本管理流程顺畅；运维人员：负责代码仓库的配置、备份、部署，严格按照规范部署对应版本的代码，配合回滚操作，保障代码部署安全。8.2监督与考核项目负责人每周对代码版本管理情况进行检查，重点检查分支命名、提交注释、评审流程、版本号使用等