Gitea CHANGELOG 深度解析：读懂 Gitea 的版本变更记录、分类规范与发布节奏

本文以 Gitea 仓库根目录下的 CHANGELOG.md 为主体，系统讲解这份变更日志的记录结构、条目分类（BREAKING / SECURITY / FEATURES / BUGFIXES 等）、版本编号与发布节奏、安全修复的组织方式，以及它与 docs/release-management.md 和 CONTRIBUTING.md 中规范之间的对应关系。读完你可以准确回答三个问题：某个 Gitea 版本引入了哪些能力、修复了哪些缺陷、破坏性变更有哪些；如何从 CHANGELOG 快速评估一次升级的影响面；以及 Gitea 的发布周期、回退移植（backport）与停止支持（EOL）策略是怎样的。

一、CHANGELOG.md 是什么：定位与总体结构

CHANGELOG.md 开头明确了自己的定位：

This changelog goes through the changes that have been made in each release without substantial changes to our git log

也就是说，它逐条记录每个发布版本中发生过的变更，但不替代 git log——变更本身不做实质性加工，只是按版本聚合呈现。当前仓库中这份文件共 6300 余行，收录了 82 个版本条目，从最早的 1.16.x 一路延续到最新的 1.27.2（2026-08-14）。文件末尾将更早的历史归档到一个独立文件中，形成两层的组织方式：

## Archived releases
* CHANGELOG-archived.md

对应的归档文件是 CHANGELOG-archived.md。这种"当前文件只保留近几个大版本、历史部分外链归档"的做法，让主 CHANGELOG 的体积可控，同时保持历史可追溯。

二、版本条目的记录格式

每个版本在 CHANGELOG 中占一个 H2 小节，格式统一为：

## [版本号] - 发布日期

以当前仓库中最近的几个条目为例（以下日期与标题均取自 CHANGELOG.md 原文）：

版本	发布日期	条目特征
1.27.2	2026-08-14	补丁版本：SECURITY + ENHANCEMENTS + BUGFIXES
1.27.1	2026-07-27	补丁版本：SECURITY + API + BUGFIXES
1.27.0	2026-07-13	功能大版本：BREAKING + SECURITY + FEATURES + ENHANCEMENTS + PERFORMANCE + BUGFIXES + TESTING + BUILD + DOCS + MISC
1.26.4	2026-06-21	安全补丁：SECURITY + BUGFIXES
1.26.3	2026-06-18	含 1 项 BREAKING 的安全/稳定性版本
1.26.2	2026-05-20	以 SECURITY 为主的大型修复版本
1.26.1	2026-04-21	纯 BUGFIXES 补丁
1.26.0	2026-04-17	功能大版本：BREAKING + SECURITY + FEATURES + PERFORMANCE + ENHANCEMENTS + BUGFIXES + REFACTOR + TESTING + BUILD + DOCS + MISC
1.25.5	2026-03-10	安全加固版本：SECURITY + ENHANCEMENTS + BUGFIXES

从这份目录可以直接观察到 Gitea 的发布节奏：

• x.y.0 功能大版本约每 3 个月一次（1.25.0 → 1.26.0 → 1.27.0，间隔分别为 2025-10-30 → 2026-04-17 → 2026-07-13 附近的节奏），条目分类最全，包含 BREAKING、FEATURES、ENHANCEMENTS、PERFORMANCE 等小节；
• x.y.1 至 x.y.n 补丁版本不定期跟随发布，条目以 SECURITY 和 BUGFIXES 为主，部分会携带零星的 BREAKING 或 API 调整（例如 1.26.3 的 BREAKING、1.26.3 的 API 小节）。

这与 docs/release-management.md 中"每三个月发布一个新主版本"（v1.26.0 in April 2026、v1.27.0 in June/July 2026、v1.28.0 in September 2026……）的排期描述一致；该文档同时说明：发布候选（v1.26.0-rc0 形式）在发布月第一周打出，若没有重大问题，维护者确认后在一两周内打出最终版本 tag。

三、条目分类：每个小节代表什么含义

CHANGELOG 在每个版本条目内部使用固定的一级分类小节，不同版本按需出现。下面结合 1.27.x 与 1.26.x 的真实条目逐一说明各分类的语义和典型内容。

BREAKING：破坏性变更（升级前必读）

这是升级评估时最需要优先阅读的分类。典型条目：

• 1.27.0：
  • Feat(actions)!: improve support for reusable workflows —— 标题中的 ! 即 Conventional Commits 的破坏性标记；
  • Use Content-Security-Policy: script nonce —— 引入 CSP 脚本 nonce，依赖内联脚本的自定义主题/插件可能受影响。
• 1.26.0：
  • Support Actions concurrency 语法；
  • Make PUBLIC_URL_DETECTION default to "auto" —— 默认值变更，属于对存量实例有行为影响的典型 breaking 项；
  • Correct swagger annotations for enums, status codes, and notification state、Remove GET API registration-token —— API 层面的破坏性调整。
• 1.26.3（补丁版本中的罕见 BREAKING）：fix(actions)!: require merged PR to bypass fork PR approval gate —— 安全相关的行为收紧也会以 BREAKING 形式标注。

按 docs/release-management.md 的回退移植规则，"We never backport breaking changes"（除非影响面极小或组件被标记为实验性），因此出现在补丁版本中的 BREAKING 条目通常意味着安全或正确性层面的强制修正，升级时应重点关注。

SECURITY：安全修复

SECURITY 小节在补丁版本中占据主导。1.26.2 是一个代表性例子，其安全条目覆盖多条防线：

• OAuth2 / token 安全：fix(oauth): bind token exchanges to the original client request、fix(oauth): strengthen PKCE validation and refresh token replay protection；
• 令牌作用域：fix: Unify public-only token filtering in API queries and repo access checks、fix(web): enforce token scopes on raw, media, and attachment downloads；
• 访问控制：fix(permissions): Fix reading permission、fix(security): enforce wiki git writes and LFS token access at request time；
• 包注册表权限：fix(packages): Add label for private and internal package and fix composor package source permission check；
• 依赖安全更新：fix(deps): update dependency mermaid to v11.15.0 [security]。

1.27.0 的 SECURITY 小节则展示了功能大版本中安全工作的密度：Fix(api): stop leaking private repo metadata after access revocation（访问撤销后不再泄露私有仓库元数据）、Fix(lfs): require proof of possession for cross-repo objects、Fix(oauth): restrict introspection to the token's client、Fix(migrations): prevent path traversal in repository restore，以及默认安全头的引入 Feat(security): set X-Content-Type-Options: nosniff by default。

对于运维方，实践建议是：无论是否跨大版本升级，都应在升级前对照目标版本的 SECURITY 小节逐项核对，因为 Gitea 的安全修复只发布在受支持的版本线上（见第五节 EOL 策略）。

FEATURES / API / ENHANCEMENTS：功能与增强

功能大版本中，FEATURES 与 ENHANCEMENTS 是最长的小节。以 1.27.0 为例，FEATURES 小节包含（原文条目节选）：

• Introduce ActionRunAttempt to represent each execution of a run —— Actions 运行模型的结构性变化；
• Serve OpenAPI 3.0 spec at /openapi.v1.json —— 提供 OpenAPI 3.0 规范端点；
• Feat(api): add token introspection and self-deletion endpoint、Feat(api): Add assignees APIs、Feat(api): add q parameter to list branches API for server-side filtering；
• Feat(oauth): Support AWS Cognito OAuth2 provider；
• Feat(web): Add Jupyter Notebook (.ipynb) Rendering Support；
• Allow multiple projects per issue and pull requests、Add bulk repository deletion for organizations；
• Feat(ssh): auto generate additional ssh keys。

ENHANCEMENTS 小节则是较小幅度的用户体验与行为改进，如 1.27.0 中的 Add pagination and search box to org teams list、Make Markdown fenced code block work with more syntaxes、Enhance(markup): improve issue title rendering 等；1.26.0 的 ENHANCEMENTS 更长，涵盖 Add actions.WORKFLOW_DIRS setting、Add DEFAULT_DELETE_BRANCH_AFTER_MERGE setting、Add chunked transfer encoding support for LFS uploads 等新增配置项与行为增强。对于使用方，ENHANCEMENTS 小节中新增的配置项名称（如 actions.WORKFLOW_DIRS、DEFAULT_DELETE_BRANCH_AFTER_MERGE）是升级后值得在 app.ini 中检查的关键信息。

PERFORMANCE：性能优化

1.27.0 的 PERFORMANCE 小节给出了几条可验证的性能改进方向：

• Perf(actions): debounce runner heartbeat writes and throttle task picks —— 减少心跳写库频率；
• Perf(web): sort the action_run query by a repo-scoped index when possible —— 查询走仓库级索引；
• Perf: extend action c_u index to include created_unix for faster dashboard feeds；
• Batch-load related data in actions run, job, and task API endpoints —— API 端点批量加载相关数据。

1.26.0 的 PERFORMANCE 小节还包括前端侧优化：Add render cache for SVG icons、Load heatmap data asynchronously、Lazy-load some Vue components、Refactor cat-file batch operations and support --batch-command approach、Use merge tree to detect conflicts when possible。这类条目帮助管理员判断某版本在大规模 Actions 使用或前端渲染场景下的性能收益。

BUGFIXES：缺陷修复

BUGFIXES 是所有版本都出现的核心小节。补丁版本几乎完全由它和 SECURITY 构成；功能大版本中它则非常庞大（1.27.0 超过 70 条）。从条目内容可以读出修复的典型层次：

• Actions 执行语义修复（1.27.1/1.27.2）：fix(actions): support matrix when evaluating workflow if expression、fix(actions): make cancelled() work in job if evaluation、fix(actions): keep github.event.inputs as strings for workflow_dispatch、fix(actions): evaluate each ${{ }} part on its own；
• 存储与基础设施：fix(storage): fix Azure Blob dump failing with file does not exist、fix: set a minio part size when the content size is unknown；
• 数据库迁移：1.27.0 中 Fix(mssql): convert legacy DATETIME columns to DATETIME2、Fix(mssql): expand legacy issue and comment long-text columns 说明 MSSQL 存量库升级有专门的列转换修复；
• 渲染与标记：fix(markdown): fix double strikethrough on code、Fix: golang html template url escaping。

TESTING / BUILD / DOCS / MISC：工程侧变更

• TESTING：测试基础设施的改进。如 1.27.0 中 Ci: shard tests and reduce redundant work、Test(e2e): run playwright via container、Remove external service dependencies in migration tests；
• BUILD：构建系统与依赖。1.27.0 中有几条值得注意：Refactor: use modernc sqlite driver as default（SQLite 默认驱动切换）、Refactor(deps): migrate from nektos/act fork to gitea/runner、Integrate renovate bot for all dependency updates；1.26.0 中 Migrate from webpack to vite、Bump min go version to 1.26.2、Convert locale files from ini to json format 等；
• DOCS：文档变更，如 Docs: add development setup guide；
• MISC：杂项重构与依赖更新，是条目最多的"兜底"分类。1.27.0 的 MISC 中包含 Replace olivere/elastic with REST API client, add OpenSearch support 这类实质性重构——从条目看，它被归入 MISC 而非 FEATURES，说明分类粒度上 MISC 并不严格等于"无关紧要"，阅读时需留意。

四、CHANGELOG 条目从哪里来：Conventional Commits 与标签机制

CHANGELOG 的条目并非人工逐条撰写，而是从合并 PR 的 Conventional Commits 标题聚合而来。这一点在 CONTRIBUTING.md 中有明确规范：

• PR 标题必须遵循 Conventional Commits 格式 type(scope)!: subject，因为 PR 采用 squash 合并，标题即成为提交信息；
• 类型取值包括 build、ci、chore、docs、feat、enhance、fix、perf、refactor、revert、style、test，其中 chore 被明确定义为"不出现于 changelog 的维护性变更"；
• 当标题前缀为 feat、enhance、fix、docs 或 test 时，CI 会自动打上对应的 type/… 标签（例如 enhance(web): … 得到 type/enhancement），并且标题修改时标签保持同步；
• ! 标记（type!: 或 type(scope)!:）表示破坏性变更——这正对应 CHANGELOG 中 BREAKING 小节里那些带 ! 的条目，如 1.27.0 的 Feat(actions)!: improve support for reusable workflows。

docs/release-management.md 则补充了流程侧：大型版本发布前，需要先在 main 分支上创建 changelog PR（聚合带 changelog 标签的 PR），合并后再打 -dev tag、创建 release/vMAJOR.MINOR 分支；发布时打签名的 tag（git tag -s -F release.notes vMAJOR.MINOR.PATCH）并推送，CI 会自动创建 release 并上传编译产物。仓库中对应的 CI 工作流文件位于 .github/workflows/release-tag-rc.yml（候选版本）、.github/workflows/release-tag-version.yml（正式版本）、.github/workflows/release-nightly.yml（每日构建）。因此从 CHANGELOG 条目反查上游 PR 时，条目尾部的 PR 编号（如 (#38894)）就是追溯原始变更的入口。

五、版本策略：分支模型、Backport 与 EOL

CHANGELOG 中版本条目的分布规律，背后是 docs/release-management.md 定义的版本策略，理解它才能正确使用这份日志。

分支与版本模型：main 是尖端分支；每个大版本对应一条 release/vX.Y 发布分支。例如 v1.26.0 若存在缺陷，修复 PR 会被提交到 release/v1.26 分支并发布 v1.26.1 tag，同时该修复也会被带回 main——这正是 CHANGELOG 中同一修复出现在补丁条目（如 1.26.1）与后续大版本中的原因。文档同时提醒：生产环境应使用最新的 release tag，而不是 main。

Backport（向下回移）规则：

1. 功能冻结已开始但 -rc0 尚未发布时，尽量多回移；
2. -rc0 发布后，只回移 bug 修复、安全修复和小型增强，大型重构不回移；
3. 新功能永不回移；
4. 破坏性变更原则上不回移，除非影响面极小或组件被标记为实验性。

回移 PR 的标题格式为 <原始 PR 标题> (#<原始 PR 编号>)，摘要首行为 Backport #<原始 PR 编号>。当前回移由 backport bot 自动执行（对应 .github/workflows/giteabot-backport.yml），当 PR 带有 backport/<version> 标签且不带 backport/manual 标签时触发；backport/manual 标签表示需要人工回移（通常因为产生了冲突）。

EOL（停止支持）策略：Gitea 按标准支持最近两个主版本。例如最新为 v1.26 时，受支持的版本线是 v1.26 与 v1.25，v1.24 及更早版本不再获得安全修复。因此运维方应以 CHANGELOG 中受支持版本线的 SECURITY 小节作为最低升级触发线：只要目标版本线仍在支持期内，安全修复就会持续出现；一旦版本线退出支持，就应当尽快升级到仍在支持期的版本。

六、实战：用 CHANGELOG 做升级影响评估

结合以上结构，一个可操作的升级评估流程是：

1. 定位版本条目：在 CHANGELOG.md 中用 Ctrl+F 搜索 ## [<目标版本>]，确认条目日期（文件头部为最新版本，条目按时间倒序排列）；
2. 先读 BREAKING：逐条确认破坏性变更是否与自身部署方式冲突。例如从 1.25 升级到 1.26 时，Make PUBLIC_URL_DETECTION default to "auto" 意味着未显式配置该值的实例行为会变化；从 1.26 升级到 1.27 时，Use Content-Security-Policy: script nonce 需要确认自定义前端脚本的兼容性；
3. 核对 SECURITY：对照自身暴露面（OAuth2、LFS、包注册表、API 令牌）检查目标版本修复的问题是否与自身相关；
4. 按模块过滤：Gitea 的修复条目普遍带 scope 前缀（fix(actions)、fix(lfs)、fix(mssql)、fix(packages)），可以直接按自身启用的模块过滤相关条目——例如不使用 Actions 的实例可以略过大部分 fix(actions) 条目；
5. 关注 BUILD 小节的基础设施变化：如 1.27.0 的 Refactor: use modernc sqlite driver as default（SQLite 驱动默认值变化）、Bump min go version（构建环境要求变化），这些影响自建二进制时的构建环境；
6. 追溯具体变更：条目末尾的 PR 编号（如 #38894）可定位原始变更内容；对于带 Backport 说明的条目，可顺藤查回原始 PR。

七、小结

CHANGELOG.md 是 Gitea 仓库中与版本升级决策直接相关的核心文档：它以"版本条目 + 分类小节 + 带 PR 编号的条目"三层结构记录了 82 个版本从 1.16.x 到 1.27.2 的全部变更，历史部分外链至 CHANGELOG-archived.md。它的分类小节（BREAKING、SECURITY、FEATURES、ENHANCEMENTS、PERFORMANCE、BUGFIXES、TESTING、BUILD、DOCS、MISC）各有明确的阅读用途；条目的来源由 CONTRIBUTING.md 的 Conventional Commits 与 type/… 标签机制保证可追溯；而条目的版本分布规律则由 docs/release-management.md 定义的三月一大版本节奏、release 分支模型、backport bot 规则与"支持最近两个主版本"的 EOL 策略所解释。对自托管运维方而言，将 BREAKING + SECURITY 两个小节作为升级检查单、按 scope 前缀过滤模块相关修复、用 PR 编号追溯细节，即可把这份 CHANGELOG 转化为一份可直接执行的升级评估清单。