Gitea 重构规范长期演进代码库中如何安全地编写、评审与合并 Refactoring PR【免费下载链接】giteaGit with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD项目地址: https://gitcode.com/GitHub_Trending/gi/giteaGitea 官方在docs/guidelines-refactoring.md中专门制定了一套重构Refactoring工作的行为规范明确了“为什么要谨慎重构”“如何写一个可被接受的重构 PR”“评审与合并阶段有哪些特殊规则”三个问题。本文以该文档为主体完整展开其全部规则并结合 Gitea 仓库中的贡献指南、社区治理文档、数据库迁移代码与迁移测试基础设施说明这些规则背后的工程逻辑帮助贡献者写出既消除技术债、又不引入回归的重构 PR。背景为什么 Gitea 的重构必须“谨慎进行”关联文档开篇就给出了前提判断Gitea 是一个体量庞大、生命周期很长的项目。随着时间推移代码库中积累了过时的机制、混合的框架和遗留代码legacy code这些都会导致 bug 或拖慢新功能的开发速度。重构是保持代码库可维护性的必要手段但必须做得足够小心——在改善代码的同时不能引入回归regressions。这个判断在仓库本身可以得到印证Gitea 的数据库结构自 1.5 版本起就经历了几百次迁移。modelmigration/migrations.go 中定义了minDBVersion 70对应 Gitea 1.5.3并在 prepareMigrationTasks 中维护了一条从 1.6 一路延续到 v28 的迁移序列按版本划分的v1_6/到v1_27/、v28/等子目录就是十余年演进留下的直接证据。正因为代码库是“长生命周期”的任何一次重构都可能触碰这些历史沉淀数据库结构、API 契约、旧框架残留所以官方才把重构从普通 PR 中单独拆出来制定了区别于常规功能/修复 PR 的规则。编写重构 PR 的八条规则docs/guidelines-refactoring.md的 “Writing a refactoring PR” 一节列出了八条要求以下逐条完整保留并展开1. 面向未来解决根因而不只是眼下的症状原规则Be forward-looking重构要处理根本原因而不是只消除当前暴露出来的那个表象。换言之重构的目标是消除“以后还会在同类地方再犯”的结构性问题例如统一散落的鉴权判断、把重复的存储抽象收敛到modules/storage这类已有抽象层而不是复制粘贴一个补丁。2. 目标是降低歧义、消除冲突、提升可维护性原规则要求重构应 Aim to reduce ambiguity and conflicts and improve maintainability。评审重构 PR 时维护者会用这把尺子衡量合并之后代码是否比之前更“自解释”、模块边界是否更清晰、重复逻辑是否减少。3. 在 PR 描述中写清楚动机rationale原规则要求 PR 描述必须回答三个问题为什么需要这次重构why the refactor is necessary它如何解决这个遗留问题how it resolves the legacy problem重构的优势与劣势advantages and disadvantages。这与 CONTRIBUTING.md 中 “PR title and summary” 一节的通用要求一致PR 标题描述“要修复的问题”而非“怎么修”第一条评论作为 summary 说明具体方案。也就是说重构 PR 的说服力完全建立在文字论证上——因为重构不带来用户可见的新功能reviewer 只能靠 rationale 判断它是否值得。4. 范围要收得紧可行范围内保持既有行为不夹带无关改动原规则Keep the scope tight在可行范围内保持现有行为不变避免把与本次重构无关的改动捆在一起。这一点与 CONTRIBUTING.md “Pull request format” 中的通用建议完全呼应不要做与 PR 无关的修改哪怕你顺手发现别的函数也想重构那应该另开一个 PR。对重构 PR 而言这条尤其关键因为“行为是否真的没变”本身就是重构 PR 最大的评审负担夹带任何功能变更都会让 reviewer 无法区分行为变化的来源。5. 把大重构拆成多个 PR 的中间步骤原规则Break large refactors into intermediate steps大型重构应当拆分为跨多个 PR 的中间步骤使其中每一个都容易评审。这是八条规则中与治理规则联动最紧密的一条docs/community-governance.md 的 “Final call” 一节明确提到如果一个 PR 被搁置超过 7 天且作者或维护者认为它“经不起等待”“such as a refactoring PR”就可以向 TOC 发起 final call。这暗示重构 PR 天然倾向于做大、做久而拆小正是为了规避这种“大 PR 长时间挂着”的风险。6. 包含验证“行为保持不变”的测试原规则Include tests that verify the behavior stays correct必须附带测试来验证重构后行为依然正确。这是重构 PR 的硬性要求而不是可选项。Gitea 仓库为这一条提供了完整的支撑设施可以据此理解“测试”具体指什么单元测试使用models/unittest与 fixturesmodels/fixtures/下有 78 个 YAML fixture 文件供各模型测试加载。数据库层面的重构有专门的迁移测试框架。modelmigration/migrationtest/tests.go 中的PrepareTestEnv会在测试开始时重置数据库unittest.ResetTestDatabase、同步指定模型、并自动加载modelmigration/fixtures/TestName目录下的 fixture如 Test_FixCommitStatusTargetURLToUseRunAndJobID 这类以测试名命名的目录。迁移函数本身如 modelmigration/v28/v343.go都配有独立的_test.go与 fixture验证“旧数据在新逻辑下被正确改写”——这正是重构“行为保持正确”的可执行证明。7. 非 bugfix 的重构尽量安排在里程碑早期原规则Prefer scheduling non-bugfix refactoring early in a milestone非 bug 修复类的重构应优先安排在里程碑milestone早期让潜在问题在发布前有充分时间暴露。这与 docs/release-management.md 的发布节奏互为因果Gitea 采用“约 2–3 个月常规开发 约 1 个月 release freeze”的周期且明确规定rc0 发布之后大型 PR如重构不再被 backport“Large PRs such as refactors are not backported anymore”。由此可以推断出一条完整的决策链重构进晚了 → 赶上 feature freeze → 无法 backport → 只能顺延到下一个大版本还会把风险压向发布稳定期。所以“越早排期越安全”不只是偏好而是发布机制的硬性约束。8. 存在分歧时升级给 TOC 裁决原规则Escalate to the TOC如果对某个重构方案有分歧应升级到Technical Oversight CommitteeTOC做最终决策。TOC 的构成与职权在 docs/community-governance.md 中有完整定义自 2023 年起Owners团队解散改由 6 人 TOC 行使所有权3 个社区选举席位 3 个公司任命席位年度选举产生。也就是说重构争议的最终裁决者是项目最高技术治理机构而不是某位资深维护者的个人意见。标题、类型与标签让重构 PR 被正确识别虽然重构规范文档本身没有展开标题格式但配套的 CONTRIBUTING.md 对重构 PR 有两处直接约束贡献者必须一并遵守Conventional Commits 标题中的refactor类型。PR 会被 squash 合并标题即最终 commit message格式为type(scope)!: subject其中refactor类型的官方定义是“A code change that neither fixes a bug nor adds a feature”既不修 bug 也不加功能的代码改动。一个典型的重构 PR 标题应写成refactor(models): unify webhook payload construction注意 CI 只对feat、enhance、fix、docs、test五种前缀自动打type/…标签refactor前缀不会自动打标需要 merger 在合并时手动补齐见 CONTRIBUTING.md “PR title and summary” 一节。type/…标签必须恰好一个。docs/community-governance.md “Labels” 一节规定type/…标签决定 PR 的类别feature、refactoring、docs、bug……应设置恰好一个。这对重构 PR 的分类、changelog 生成和 backport 判断都有下游影响。评审与合并重构 PR 的“宽松时钟”docs/guidelines-refactoring.md的 “Reviewing and merging” 一节给出了四条合并期规则其中包含两条只适用于重构类 PR 的特殊宽限1. 让重构 PR 短命通常不超过 7 天规则要求重构 PR 保持短生命周期typically no more than 7 days采用快速的评审节奏并尽快合并避免它被无关的工作阻塞、越拖越旧。这与 CONTRIBUTING.md “Maintaining open PRs” 的通用纪律一致评审开始后不要 rebase 或 squash 自己的分支只在必要时如出现冲突才把 base 分支合并进来以限制不必要的 CI 运行所有 PR 最终都是 squash 合并。2. 7 天后非作者核心成员可以“单人批准并合并”这是重构 PR 相对普通 PR 最重要的差异化条款普通 PR 需要两名维护者批准docs/community-governance.md “Review expectations”“Every PR must be reviewed by at least two maintainers (or owners) before merge”而该文档同时给出例外——“after one week, refactoring PRs and documentation-only PRs need only one maintainer approval”。重构规范文档用另一种措辞表达了同一条规则如果 TOC 没有提出异议一名非作者的核心成员在 7 天之后就可以批准并合并该重构 PR。两份文档互为印证重构 PR 不会因为“凑不齐第二个人点头”而无限期卡住等待超过一周本身就是一种时间信号。3. 接受不完美但方向正确的中间态实现规则明确只要最终结果让代码库变得更好就接受不完美的中间实现accept imperfect intermediate implementations。这条与“拆分成多个 PR 的中间步骤”形成闭环——拆分必然产生过渡态代码临时的兼容层、双写、别名导出等评审者不应以“这个中间态不够优雅”为由 block只要路线图清晰、终点更好。4. 必要的重构允许“临时回归”但必须立即修复规则允许一个由必要重构造成的临时回归temporary regression前提是它随后被及时修复fixed promptly afterwards。这条把“重构可能短期伤害行为”这一事实制度化了与其要求重构者做到零副作用往往导致重构被无限搁置不如承认过渡性风险用“promptly”这一时限约束来控制风险敞口。与治理机制的联动final call、合并队列与回退重构规范中的“7 天”不是孤立数字它与 docs/community-governance.md 的三套机制咬合Final call最终裁决请求PR 被忽略超过 7 天、无评论无评审且作者或任一维护者判断它经不起等待文档点名了 “such as a refactoring PR”可在评论中 TOC 发起 final call。再过 7 天仍零批准则视为“礼貌性拒绝”PR 被关闭若无维护者反对则 TOC 一人批准非作者即可合并。文档特别提示 final call 有成本应谨慎使用。合并队列merge queue满足双批准或重构类的单批准宽限、带lgtm/done、无未决讨论、无冲突的 PR 进入reviewed/wait-merge队列由 merger 按入队顺序合并。重构 PR 在获得批准后的“落地”依赖这条流水线因此“尽快合并”不只是口号。回退边界如前所述docs/release-management.md 规定 rc0 之后不再 backport 重构类大 PR且 backport bot 在合并后自动创建 backport PR除非打了backport/manual标签。因此重构 PR 的排期决策实际上同时决定了它进入哪个版本的变更集。典型重构案例路径修改数据库持久化结构“谨慎重构”在 Gitea 里最典型的场景是修改models/下的数据库持久化结构。docs/development.md “Database migrations” 一节给出了标准流程可以视为重构规范在特定技术领域的落地版本识别破坏性变更只要对models/下某个入库结构做了 breaking change改列名、改类型、改默认值就不能只改 Go 结构体必须在modelmigration/下新增一条迁移。按序号追加迁移新迁移追加在 modelmigration/migrations.go 迁移序列的底部形如newMigration(352, your migration description, v28.YourMigrationFunc),文件头注释写明了两条纪律“Add new migrations to the bottom of the list”新迁移加到列表底部若要“退休”一条迁移则从列表顶部移除并同步更新minDBVersion。这套机制保证了老数据库版本只能向前升级重构不能“回改”历史结构——这正是“保持既有行为”在数据层的体现。迁移执行带全局锁services/versioned_migration/migration.go 中的Migrate函数会先通过globallock.Lock(ctx, gitea_versioned_migration)加分布式锁再调用modelmigration.Migrate确保多实例部署下同一时刻只有一个实例执行迁移。用 fixture 驱动的测试验证按照重构规范第 6 条为该迁移编写Test_xxx测试PrepareTestEnv会自动从modelmigration/fixtures/TestName/加载“迁移前”的数据快照YAML fixture测试断言迁移执行后数据库状态符合预期。仓库中 17 个 fixture 目录如 Test_FixCommitStatusTargetURLToUseRunAndJobID都是这种“旧数据 → 迁移 → 验证”模式的实例。对读者来说这条路径演示了重构规范的核心思想如何落到工程细节范围紧一条迁移一个 PR、行为可验证fixture 测试、风险有边界全局锁 只向前迁移。小结重构规范的实际约束清单把docs/guidelines-refactoring.md与配套治理文档合起来一个可执行的重构 PR 检查清单是阶段要求依据立项针对根因能降低歧义/冲突排期在里程碑早期docs/guidelines-refactoring.md描述写清 why / how / 优缺点标题用refactor(scope): …docs/guidelines-refactoring.md、CONTRIBUTING.md拆分大重构拆为多个可独立评审的 PR不夹带无关改动DB 结构变更走modelmigration/docs/guidelines-refactoring.md、docs/development.md测试附验证“行为保持不变”的测试模型层用 fixtures/迁移测试docs/guidelines-refactoring.md、modelmigration/migrationtest/tests.go评审通常 7 天内走完评审中间态可接受临时回归须立即修复docs/guidelines-refactoring.md合并7 天后非作者核心成员可单人批准合并TOC 无异议时type/…标签由 merger 补齐docs/community-governance.md分歧/搁置方案分歧升级 TOC7 天无响应可发起 final calldocs/guidelines-refactoring.md、docs/community-governance.md发布rc0 之后重构不再 backportdocs/release-management.md这套规范的设计哲学可以概括为一句话Gitea 并不反对“先过渡、后完善”的重构路径但它用动机说明、范围纪律、行为测试、7 天时钟和 TOC 兜底五道机制确保每一次重构都是可评审、可回退、可追溯地改善代码库。【免费下载链接】giteaGit with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD项目地址: https://gitcode.com/GitHub_Trending/gi/gitea创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考