第四十四章 版本管理

篇别：第十二篇 版本管理与升级

本章学习目标

  • 使用 Git 分支策略 管理 自定义模块与多环境。
  • 理解 __manifest__.py 版本号 与 OCA/社区惯例。
  • 编写与运行 数据库迁移脚本（升级 -u），理解 pre / post / end-migrate 阶段。
  • 了解 Upgrade Utils、upgrade_code 在 大版本升级 中的角色。

导读：版本管理 = 代码 + 数据

Git 管 代码线；PostgreSQL 里 ir_module_module、业务表 管 数据形态。跨 Odoo 大版本 时，仅合并代码不够，必须 迁移脚本 与 升级预演。本章与 第二十七章（规范）、第四十三章（CI） 衔接。

44.1 Git 工作流

44.1.1 知识要点

  • main：可发布 快照；保护分支，仅 PR 合并。
  • develop 或 version/19.0：集成 分支；Nightly / CI 目标。
  • feature/*、fix/*：短生命周期；rebase 或 merge 由团队选。
  • 子模块：企业版/OCA 用 git submodule 时 固定 commit；升级子模块 单独 PR。
  • Tag：v19.0.1.0.0 对齐 模块版本；发版说明 附 迁移注意。

44.1.2 案例

GitFlow 简版：hotfix 从 main 切 → 合并 main + develop。

44.1.3 截图占位

图 44-1 Git 分支图

44.1.4 本节练习

  1. 实操：为一次模块发布打 v19.0.1.0.0 标签并写 三行 release note。
  2. 简答：直接在 main 开发 对 多环境并行 的问题？

参考答案提示：2. 不稳定主干、难回滚、CI 噪声。

44.2 模块版本

44.2.1 知识要点

  • version 字段：19.0.x.y.z OCA 常见：Odoo 主版本.系列.主.次.修订。
  • 语义：x 大功能、y 兼容扩展、z 补丁。
  • 依赖：depends 版本范围 少用 过宽，避免 隐性破坏。
  • 发布：PyPI/OCA 另有规范；内部模块 至少 自洽递增。

44.2.2 案例

# __manifest__.py
"version": "19.0.1.2.0",

44.2.3 本节练习

  1. 简答：19.0.1.0.0 各段 常见含义（OCA 惯例）？
  2. 判断：version 字符串 变化会 自动 触发 数据迁移脚本。（ ）

参考答案提示：1. Odoo 主版本.系列.主版本.次版本.修订。2. 错；须 migrate 脚本命名与版本 规则配合。

44.3 数据库迁移

44.3.1 知识要点

  • -u module：加载 Python/XML 并执行 migrations/ 下脚本（路径规则以版本为准）。
  • 备份：升级前 pg_dump + filestore；失败 可还原。
  • 预演：副本库 先跑；记录耗时 与 锁表窗口。
  • 多步：大表改列 拆 online / batch；避免 峰值 ACCESS EXCLUSIVE 过久。

44.3.2 案例

失败处理：保留 traceback、数据库版本、已执行脚本标记（若有），勿半状态手工乱改。

44.3.3 截图占位

图 44-3 升级报错 traceback（测试库）

44.3.4 本节练习

  1. 实操：在 副本库 执行 -u my_module 并 记录首次失败栈。
  2. 简答：生产升级 窗口沟通 三条（用户、备份、回滚）。

参考答案提示：2. 公告维护时间、只读模式、联系人。

44.4 升级脚本阶段（新增）

44.4.1 知识要点

  • pre-migrate：新代码 ORM 尚未可用；适合 ALTER TABLE、删列前搬数据。
  • post-migrate：新模型已加载；适合 env 级数据修复、重算字段。
  • end-migrate：收尾、清理临时表；少用长事务。
  • 命名与版本：目录名与目标版本 对齐官方约定（查阅当前版本文档）。

44.4.2 案例

pre：重命名列 x_old → x_new；post：env['my.model'].search([]).write({'checksum': False}) 触发重算（慎用全表）。

44.4.3 截图占位

图 44-4 migrations 目录结构与版本子目录

44.4.4 本节练习

  1. 简答：哪些操作 必须 在 pre-migrate 完成？
  2. 判断：post-migrate 里 env.user 一定是 admin。（ ）

参考答案提示：1. 破坏性与 ORM 不兼容的 DDL。2. 视 运行上下文；勿依赖，显式 browse SUPERUSER 若需要。

44.5 Upgrade Utils（新增）

44.5.1 知识要点

  • 官方工具库：辅助 改名、合并模型、数据清洗（企业版升级服务 常配合使用）。
  • 社区：自建迁移 可 部分复用；阅读文档 再 调用，避免隐式魔法。
  • 测试：Utils 调用 也须 单元测试 / 副本库验证。

44.5.2 案例

场景：合并 product.supplierinfo 扩展字段 → 查 Utils 是否提供 rename + merge 助手。

44.5.3 截图占位

图 44-5 Upgrade Utils 文档或 pip 包说明

44.5.4 本节练习

  1. 拓展：企业版升级服务 与 社区自建迁移 的差异（责任、时效、范围）。
  2. 简答：Upgrade Utils 能否 替代 业务顾问 验收测试？

参考答案提示：2. 不能；业务规则 仍需 UAT。

44.6 upgrade_code 命令（新增）

44.6.1 知识要点

  • 用途：Odoo 19 提供 源码级自动重写（废弃 API、路由类型 等），减少机械劳动。
  • 流程：分支上 git commit 快照 → 运行工具 → git diff 人工审查 → 测试。
  • 边界：语义复杂处 工具会错；三目运算、动态 getattr 高危。

44.6.2 案例

# 示意：以官方 CLI 文档为准
# odoo-bin upgrade_code --help

纪律：禁止 不审查就合并。

44.6.3 截图占位

图 44-6 upgrade_code diff 预览

44.6.4 本节练习

  1. 实操：对 小型模块 跑一次 upgrade_code 并 人工合并。
  2. 简答：工具改写 后 必跑 哪三类检查？

参考答案提示：2. ruff/测试、关键路径手工、安全相关 grep（csrf、sudo）。

本章综合练习

  1. 回滚：升级失败 后的 数据库与代码回滚步骤（有序列表）。
  2. 数据：跨版本 rename model 时 ir.model.data 与 外键 的处理思路。
  3. 综合：从 17 到 19 的 检查表（Python 版本、废弃 API、资产、迁移脚本 不少于 5 项）。
  4. 实操：为团队写 「迁移 PR 模板」（备份证明、预演记录、回滚负责人）。

本章对应白皮书目录：第四十四章 版本管理。