Baserow Changelog 解析：JSON 条目驱动的机器化版本发布记录与 changelog 生成工具链

Baserow Changelog 解析JSON 条目驱动的机器化版本发布记录与 changelog 生成工具链【免费下载链接】baserowBuild databases, automations, apps agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserowBaserow 仓库根目录的 changelog.md约 3500 行是项目全部已发布版本的完整变更记录从 2.0 时代一直记录到当前最新的 2.3.3 版本。与常见的“人手维护 CHANGELOG”不同它是由仓库内 changelog/ 目录下的生成工具基于逐条 JSON 条目自动编译而成的每条变更都对应一个可独立提交的 JSON 文件发布时统一打包进releases.json元数据并重新渲染出整份 Markdown。读完本文你既能快速读懂 changelog.md 的条目分类与版本脉络也能掌握just changelog工具链的完整工作流知道一条新功能记录从 JSON 文件到最终 Markdown 条目的整条数据流。changelog.md 的文档结构按版本倒序、按类型分节的记录格式当前 changelog.md 的组织方式非常规整理解这个格式是读懂整个文件的前提顶层以## Released 版本号划分版本块版本号严格从新到旧排列当前文件以## Released 2.3.3开头最底部是早期的 1.x 版本。版本块的先后顺序不是按文件夹名字典序排的而是由 releases.json 中releases数组的顺序决定——这是生成器 ChangelogHandler.order_release_folders 的核心逻辑后续小节会展开。每个版本块内按四种固定子节分类### New features新功能、### Bug fixes缺陷修复、### Refactors重构、### Breaking API changes破坏性 API 变更。某个版本若没有某类条目该子节直接省略不渲染见 handler.py 的生成循环。每条条目都以[领域前缀] 消息文本 #issue号的格式呈现。领域前缀取自 domains.py 中定义的六个模块域[Core]、[Database]、[Builder]、[Automation]、[Integration]、[Dashboard]。例如 2.3.3 中的[Core] Monitor celery beat periodic tasks with Sentry cron monitors when Sentry is enabled前缀[Core]表明这是后端核心非数据库层面的改动。这套“版本 × 类型 × 域”的三维分类使得一份几千行的记录依然可以被人和工具高效检索找破坏性变更只需搜Breaking API changes找某模块的历史只需看[Database]前缀。底层数据模型一条 changelog 就是一个 JSON 文件changelog.md 本身不是手工写的也不应该被手工编辑。真实的数据源位于 changelog/entries/ 目录每个已发布版本对应一个以版本号命名的文件夹如2.3.3/、2.3.0/、1.35.0/文件夹内部再按条目类型分目录存放 JSON 文件。当前尚待发布的条目统一放在 changelog/entries/unreleased/ 下其内部已有按类型预建的四个空目录feature/、bug/、refactor/、breaking_change/——这正对应 changelog.md 中看到的四种子节标题。一个 JSON 条目的字段结构由 ChangelogEntry.generate_entry_dict 定义{ type: bug, message: Fixed a bug ..., issue_origin: github, issue_number: 5147, domain: database, bullet_points: [], created_at: 2026-07-15 }type取值于 changelog_entry.py 中的四个类——featureNew features、bugBug fixes、refactorRefactors、breaking_changeBreaking API changesmessage面向用户的非技术性描述domain上节所述的六个模块域之一issue_originissue_number条目来源仓库github或gitlab与 issue 编号渲染时会拼成 Markdown 链接逻辑见 get_markdown_stringbullet_points可选的二级子列表主要用于模板发布等场景handler.py 会以缩进两格的*形式渲染在其主条目下方created_at条目创建日期。文件名则由 generate_entry_file_name 规则生成若有 issue 号则以{issue_number}_开头消息体去掉句点、空格转下划线、剔除特殊字符、转小写后截断到 60 字符再加.json。这意味着同一 issue 的两条同消息条目会互相覆盖handler 会打印覆盖提示不同条目天然通过文件名隔离——这正是“无冲突提交”设计的基础。生成器调用链从 add_entry 到 changelog.md生成工具是一个基于typer的 Python CLI入口在 changelog/src/changelog.py核心逻辑在 changelog/src/handler.py 的ChangelogHandler类。三个关键属性定义了它的工作目录约定property def release_meta_data_file_path(self): return f{self.working_dir}/releases.json # changelog/releases.json property def entries_file_path(self): return f{self.working_dir}/entries # changelog/entries/ property def changelog_path(self): return f{self.working_dir}/../changelog.md # 仓库根目录的 changelog.md由此可以看出整条数据流changelog/entries/release/type/*.json→ChangelogHandler聚合排序 → 仓库根目录 changelog.md。生成 Markdown 时的具体规则见 generate_changelog_markdown_file包括遍历entries/下所有版本文件夹跳过unreleased按 releases.json 的数组顺序排列版本找不到的版本会打印警告并省略对每个版本先写## Released {版本号}标题再按条目类型写### New features等子节标题每条消息前自动拼上该条目的领域前缀[Domain]旧条目若无domain字段则不加前缀兼容历史数据。命令工作流just changelog 的四个子命令所有 changelog 命令都通过仓库根 justfile 中的changelog配方转发第 1226-1228 行附近# Run changelog command (e.g., just changelog add, just changelog release 2.3.3) [doc(Changelog: just changelog add|release|generate|purge)] changelog *args: cd backend uv run --group changelog python ../changelog/src/changelog.py $也就是说实际执行的是 backend 的 uv 虚拟环境里运行changelog/src/changelog.py脚本参数原样透传。四个子命令及其源码行为如下1.just changelog add新增一条待发布条目交互式询问四个字段也可以全量传参非交互执行add 命令实现# 交互模式逐项提示 Domain / Type of changelog / Issue number / Message just changelog add # 非交互模式CI 友好 just changelog add --domain database --type feature \ --message Add clear button to the view search --issue 2753--domain可选值core, dashboard, database, builder, automation, integration默认database--type可选值feature, bug, refactor, breaking_change默认bug--issueGitHub issue 号。不传时会尝试从当前 git 分支名解析——get_issue_number 执行git rev-parse --abbrev-ref HEAD并取分支名-分隔的首段作为 issue 号例如分支5702-presence-bar会解析出 5702解析失败则为空--message要求用非技术性语言描述该变更“达成了什么”因为它会直接成为 changelog.md 里的最终文案。条目落盘到changelog/entries/unreleased/type/文件名.jsonissue_origin固定写为github。2.just changelog release name发布一个版本release 命令 依次执行三步与 changelog/README.md 描述一致just changelog release 2.3.3move_entries_to_release_folder把entries/unreleased/整体复制到entries/2.3.3/随后删除 unreleased 里的全部 JSON、清理空目录与.gitkeep因此发布后 unreleased 下的四个类型目录保留为空壳等待下一个发布周期write_release_meta_data向 releases.json 的releases数组头部插入{name: 2.3.3, created_at: 2026-07-21}——数组头部插入正是 changelog.md 中版本“新在前”顺序的来源generate_changelog_markdown_file重新渲染仓库根目录的 changelog.md。版本号名必须与entries/下已有文件夹不重名release 命令 会先做唯一性校验并抛错。发布完成后按 changelog/README.md 的说明生成的changelog.md会被移到项目根目录当前仓库根目录下的这份即产物。3.just changelog generate仅重新渲染generate 命令 只调用generate_changelog_markdown_file()不移动任何条目、不改releases.json。两个典型用途直接手改了某个 JSON 条目内容后重新出稿调整了 releases.json 中版本顺序后刷新文档。4.just changelog purge危险操作purge 命令 会删除entries/目录、releases.json和生成的changelog.md三样东西且不可恢复。正常开发流程几乎用不到它changelog/README.md 也特别标注了“Be careful when running purge”。条目如何渲染为链接GitHub 与 GitLab 双来源changelog.md 中每条带 issue 号的条目末尾都有一个链接链接目标由issue_origin字段决定get_markdown_stringissue_origin: github→https://github.com/baserow/baserow/issues/编号issue_origin: gitlab兼容旧条目的默认值→https://gitlab.com/baserow/baserow/-/issues/编号。这解释了为什么当前文件中 2.3.x 时代的条目几乎都指向 GitHub issues如 2.3.2 中[#5147](https://github.com/baserow/baserow/issues/5147)而部分更早的条目如 2.3.1 中的[#5660](https://gitlab.com/baserow/baserow/-/issues/5660)仍指向 GitLab——项目追踪器从 GitLab 迁移到 GitHub 的时间线恰好可以从链接域名上读出来。所有新建条目则一律写死为githubchangelog.py 第 81 行。用 changelog 读懂近期演进2.3.0 大版本与 2.3.x 安全加固把 changelog.md 当作版本演进的时间线来读近期几个版本信息量很大2.3.02026-07-07 发布一个以公式、集成和 Builder 能力为核心的大版本从 changelog 条目可以归纳出 2.3.0 的几条主线公式/表达式能力扩张新增运行时公式number_format()、abs()、null()、to_duration()、to_datetime()、range()、duration_format()支持 duration 算术运算以及to_json()/from_json()表达式条目分别引用 issue #4974、#5420、#5559、#3879集成与自动化平台化新增 Code service在工作流/Builder 中执行任意 JavaScript#5424、CSV reader 与 XLS[X] reader service、行批量增删改操作#5543、Start workflowaction 与手动触发器#5561以及“字段值变更才触发”的精准工作流触发器BuilderApplication Builder成型页面与元素级 undo/redo 与回收站、拖放交互改进#5143、列布局预设、成员管理members management扩展到应用/自动化/仪表盘数据库体验Kanban 视图支持排序#764、网格视图分组折叠展开#2257、Excel 导入、导出时可选择去掉行 ID 与主字段列#4680等基础设施默认开启缓存、WebSocket 连接/断开指标、drop_tsv_columns管理命令用于清理不再使用的全文检索列。2.3.0 也带有一条明确的破坏性 API 变更移动行reorder不再更新updated_on字段依赖它的“最后修改时间”类公式在重排行时不再重算#3054——对依赖行排序变更触发公式更新的集成方需要注意。2.3.32026-07-21 发布SSRF 防护等安全项值得关注自托管运维最新的 2.3.3 版本条目对自托管部署者有两条直接可操作的环境变量配置数据同步从用户自定义 URL 拉取如自托管 GitLab/Jira 实例或 iCal 源现在可通过将BASEROW_DATA_SYNC_ALLOW_PRIVATE_ADDRESS设为false阻止访问私有网络地址管理端可配置 URL 的 OAuth2 / OpenID Connect SSO 提供商同理支持BASEROW_SSO_ALLOW_PRIVATE_ADDRESS。这两条不是空泛的文档后端源码可以印证其实现。BASEROW_DATA_SYNC_ALLOW_PRIVATE_ADDRESS在 base.py 设置 中定义为布尔环境变量且默认值为true向后兼容data_sync/utils.py 中的get_data_sync_request_function()与get_data_sync_session()据此二选一返回普通requests客户端还是advocate客户端——后者会拒绝解析到私有网络地址的 URL且只放行 80、443、8000、8080、8443 端口见 DATA_SYNC_BLOCKED_URL_ERROR 的用户可见报错文案。测试配置 test.py 中则直接把两个变量都固定为False说明测试环境默认走最严格的 SSRF 防护路径。2.3.x 各小版本还密集修复了一批安全相关缺陷读 changelog 时可以一并留意密码重置 token 改为一次性使用且有效期缩短至 1 小时2.2.1#5165、防恶意显示名在富文本 mention 中执行脚本、阻止 CSV/Excel 导出的电子表格公式注入2.3.0、加固用户上传媒体文件的投递与激活内容中和2.2.2、后台依赖升级修复已知安全漏洞2.3.0。给贡献者与维护者的实用约定综合 changelog/README.md 的 FAQ 与源码行为维护这份 changelog 需要遵守的约定可以归纳为每条变更都提交一个 JSON 条目随 MR 一起进入版本控制条目放changelog/entries/unreleased/type/下这是避免多人同周期编辑changelog.md产生合并冲突的根本手段README FAQ 明确解释了该工具的诞生动机此前手改 changelog.md 导致频繁合并冲突并浪费 CI 时间不要手工编辑 changelog.md——它是纯生成产物每次generate/release都会整体重写手改内容必然丢失发布后发现条目写错直接改对应版本文件夹里的 JSON 文件再跑just changelog generate即可无需重建整个 release需要条目下的子弹列表如新增模板清单时直接编辑 JSON 的bullet_points字段——CLI 目前不提示该字段属于边缘用例想调整版本在文档中的展示顺序唯一办法是移动 releases.jsonreleases数组里的条目位置。小结changelog.md 之于 Baserow既是一份面向用户的版本历史也是一套可审计的发布流水账JSON 条目changelog/entries/版本/类型/*.json是事实来源ChangelogHandler 负责聚合、排序与渲染just changelog四个子命令覆盖新增、发布、重渲染与清理全生命周期。对贡献者而言记住“先just changelog add提交 JSON、发布由just changelog release 版本号一次性完成”即可无缝参与对使用者与运维者而言按## Released版本块 四个类型子节 [Domain]前缀的检索方式可以快速定位任一功能的引入版本、破坏性变更与安全加固记录——这正是这份机器生成的 3500 行文档持续保持结构一致、可机读可检索的原因。【免费下载链接】baserowBuild databases, automations, apps agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考