Read the Docs 官方 Changelog 全解析：从版本发布机制到演进历史

后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载Read the Docsreadthedocs.org是托管与构建软件文档的核心平台。本文以仓库中的 用户文档 Changelog 页面 及其真正的内容来源 CHANGELOG.rst 为骨架系统梳理该项目从 2.0 时代到 14.0.0 的版本发布机制、SemVer 版本策略、2025 年 6 月起迁移到 GitHub Releases 的自动化流程以及各版本背后可追溯的源码事实。读完本文你将掌握如何阅读与使用这份 changelog、理解其版本号格式的演变以及从历史条目中反查对应实现代码的方法。一、Changelog 页面与真实内容来源在仓库中用户文档的 Changelog 页面 正文非常简短它通过 RST 的include指令直接嵌入仓库根目录的 CHANGELOG.rst实际内容全部由后者提供.. include:: ../../CHANGELOG.rst也就是说根目录的 CHANGELOG.rst 才是唯一的事实来源用户文档页面只是它的一个渲染入口。这是典型的单一事实来源Single Source of Truth实践发布时只需维护根目录文件所有引用它的页面自动同步更新。页面同时指出一个重要的历史分界点自 2.0 版本起Read the Docs 开始遵循语义化版本Semantic Versioning原则进行版本递增并尝试自动化更新 changelog页面下方保留了 2015 年 7 月 23 日的少数历史记录作为过去曾尝试在此补充信息的样例此后不再在该页面手工维护。二、版本号机制从 2.0 到 14.0.0 再到日期版本2.1 早期的 SemVer 阶段从 CHANGELOG.rst 的版本标题可以看出项目长期使用主.次.补丁三段式版本号例如Version 2.0.0、Version 5.0.0、Version 11.0.0。其中几个大版本有明确的语义里程碑11.0.02024 年 6 月 11 日该版本明确标注移除对 Git 之外 VCS 系统的支持对应合并的 PR 为VCS: remove code for old VCS support属于破坏性变更因此递增主版本号。13.0.02025 年 4 月 29 日升级到 Django 5.xUpgrade to Django 5.x同样伴随破坏性变更。14.0.02025 年 6 月 24 日开始尝试使用GitHub 自动生成的 Changelog这是发布流程转型的起点。2.2 2025 年 6 月 30 日后的日期版本CHANGELOG.rst 开头的note明确写道自 2025 年 6 月 30 日起changelog 改为以 GitHub Release 形式发布并直接列在仓库的 Releases 页面中。与此对应仓库中的版本管理工具配置也已经切换为bumpver 日期版本模式。查看 setup.cfg 中的[bumpver]段[bumpver] current_version 2026.09.22 version_pattern YYYY.0M.0D[TAGNUM] commit_message Bump version {old_version} - {new_version} commit False tag False push False [bumpver:file_patterns] setup.cfg version {version} current_version {version} docs/conf.py version {version} readthedocs/__init__.py __version__ {version}version_pattern为YYYY.0M.0D即按日历日期发布当前仓库版本为2026.09.22。bumpver 会在三处同步更新版本号setup.cfg 的version 2026.09.22包元数据docs/conf.py 的version 2026.09.22与release versionSphinx 文档构建版本readthedocs/init.py 的__version__ 2026.09.22Python 运行时版本常量。这三处版本号由工具统一切换避免了手工维护导致的版本不一致。这正是版本号、文档构建、运行时三端一致的自动化实现也是理解当前仓库版本状态的钥匙。三、当前仓库的版本发布自动化闭环将 changelog 的 note 与源码配置交叉验证可以还原出当前截至仓库所反映的状态的发布自动化闭环版本号由 bumpver 按YYYY.0M.0D模式统一更新同步写入 setup.cfg、docs/conf.py 与 readthedocs/init.py变更记录从 14.0.0 起由 GitHub 的自动生成 Changelog 能力产出不再在 CHANGELOG.rst 内手工撰写逐条说明文档页面docs/user/changelog.rst继续通过include引用根目录 CHANGELOG.rst作为历史存档入口保留。需要说明的是CHANGELOG.rst 中 13.5.0 及之前各版本的条目均为作者 PR 标题 PR 链接的 GitHub 风格格式而 14.0.0 及之后的正式发布改由 GitHub Releases 承载——从仓库文件本身可以确认 14.0.0 是试用自动生成 Changelog的最后一个写入 CHANGELOG.rst 的版本。四、历史版本条目如何反查源码以 2015 年 Django 1.8 升级为例用户文档页面保留的 2015 年 7 月 23 日历史记录是理解changelog 条目与源码对应关系的绝佳案例。该条目记录了 Django 1.8 支持合并的技术细节依赖升级清单Django1.6.11 → 1.8.3django-celery3.0.23 → 3.1.26Celery3.0.24 → 3.1.18tastypie 从0.11.1升级到指定 commit1e1aff3dd4dcd21669e9c68bd7681253b286b856django-oauth0.16.1 → 0.21.0django-guardian1.2.0 → 1.3.0pytest-django2.6.2 → 2.8.0psycopg22.4 → 2.4.6。架构迁移移除 South将全部迁移移植到 Django 原生迁移框架改用django-formtools替代被移除的django.contrib.formtools在conf.py中加入django.setup()以正确加载 Django 环境为readthedocs/目录下所有含模型的 app 新增迁移文件。部署命令升级后需要在服务器执行以下命令python manage.py migrate contenttypes python manage.py migrate projects 0002 --fake python manage.py migrate --fake-initial其中--fake与--fake-initial用于在历史数据库上假装应用已有迁移避免与旧 South 迁移状态冲突。文档还提示若本地 pip 未能将 tastypie 升级到指定 commit部署时应使用pip install -U -r requirements/deploy.txt对应仓库中的 requirements/deploy.in 与 requirements/deploy.txt。开发环境升级步骤先确保迁移已应用python manage.py syncdb与python manage.py migrate然后git pull、pip install -r requirements.txt最后同样执行上述三条 fake 迁移命令。这一历史条目展示了 Read the Docs 处理框架大版本升级 迁移框架切换时的完整方法论依赖逐个升级、代码适配、迁移兼容、部署与开发双路径命令。即使这些命令今天已不适用现代 Django 已无syncdb它依然是研究该项目升级策略的珍贵史料。五、从近两年 Changelog 看平台演进主线对 CHANGELOG.rst 中 10.x–13.x 条目的归纳可以勾勒出 Read the Docs 平台近两年的主要演进方向均为仓库内可核验的事实演进主题代表性变更CHANGELOG.rst 条目对应源码/配置位置仓库现状前端重构多期New dashboard: delete legacy HTML templates、移除旧 dashboard 与新看板切换app.域名替代beta.readthedocs/templates/projects/ 下的 58 个 HTML 模板构建系统支持 Ubuntu 24.04 LTS、build.commands与build.jobs文档化、构建工具版本化更新、Build: show the command thats currently being executedreadthedocs/doc_builder/ 与 readthedocs/builds/Addons 体系AddonsConfig 模型、flyout 位置可配置、视觉差异Visual diff / File Tree Diff默认开启readthedocs/filetreediff/ 及相关模型认证与 SSOallauth 升级、2FA 支持、SAML 更新、GitHub App OAuth 提供方与迁移页readthedocs/allauth/、readthedocs/sso/搜索与索引索引前截断内容、搜索索引流程重构、间距保留、remove from ES 阈值设置readthedocs/search/API v3权限收紧匿名访问公共资源、防信息泄漏的受限序列化器、rate limit 与分页文档化readthedocs/api/v3/基础设施Django 5.2 / 4.2 来回调整、Redis 降级、psycopg v3、pip-tools 自动依赖 PR、Ruff 引入requirements/deploy.in、requirements/pip.in这种changelog 条目 → 源码目录的对应检索方式正是把一份发布记录变成可操作技术地图的关键技巧。六、如何在自己的文档项目中复刻这套 Changelog 机制Read the Docs 的这套实践对任何开源项目都有直接的借鉴价值核心三原则单一事实来源用.. include::RST或{{% include %}}Markdown把根目录 CHANGELOG 引入文档页面杜绝重复维护自动化版本同步采用 bumpver 这类工具让包元数据setup.cfg、Sphinx 文档docs/conf.py、运行时版本常量__init__.py三处版本号在一次命令内全部更新模式可自定义为 SemVer 或日期版本自动生成变更记录当项目发布频率变高后可像 Read the Docs 14.0.0 那样切换到平台的自动 Changelog 能力让 PR 标题直接成为发布说明同时保留历史 CHANGELOG 文件作为归档。七、总结用户文档 Changelog 页面 只是入口真正的技术含量沉淀在根目录的 CHANGELOG.rst 与配套的版本工具链中。从 2015 年手工维护的 Django 1.8 升级记录到 2025 年 14.0.0 试水 GitHub 自动生成 Changelog再到当前 setup.cfg 中的YYYY.0M.0D日期版本模式Read the Docs 的 changelog 本身就是一部浓缩的工程演进史。借助这份 changelog 反查 readthedocs/ 下的源码你可以在几分钟内定位任何一个历史功能对应的现代实现。赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐Hippy 的 Voltron VFS 模块版本演进与发布历史CHANGELOG 全解析Hippy 的 Voltron VFS 模块版本演进与发布历史CHANGELOG 全解析 本篇指南围绕开源仓库 modules/vfs/voltron/CH跨平台移动开发前端Jekyll 版本历史解析从 v0.0.0 到 v4.4.1 的技术演进与 Changelog 生成机制Jekyll 版本历史解析从 v0.0.0 到 v4.4.1 的技术演进与 Changelog 生成机制 本文基于 Jekyll 官方仓库的 History前端CMSNetBox 版本发布机制与版本历史全解析从语义化版本号到 v4.7 功能演进NetBox 版本发布机制与版本历史全解析从语义化版本号到 v4.7 功能演进 NetBox 采用主版本Major/次版本Minor/补丁版本Pat后端网络数据建模上一篇终极指南如何零风险免费激活Cursor Pro版本下一篇MemcachedNode.js的高性能缓存解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考