Remotion 文档发布流程：如何把 PR 中的 AvailableFrom 更新为下一个补丁版本

Remotion 文档发布流程：如何把 PR 中的 AvailableFrom 更新为下一个补丁版本

【免费下载链接】remotion🎥 Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion

在 Remotion 仓库中，每一篇文档页面都可以用<AvailableFrom v="...">组件标注某个 API、命令或功能是从哪个版本开始可用的。当 PR 包含文档改动且引入了新的AvailableFrom标注时，其取值必须反映"下一个将发布的版本"，而不是main分支上已经存在的旧版本。本文以仓库中.agents/skills/update-version/SKILL.md这份 Agent 技能文档为核心，完整讲解这套"取main版本 → 计算下一个补丁版本 → 只改本 PR 触及的条目 → 提交推送"的操作流程，并结合packages/core/src/version.ts、packages/docs/src/components/AvailableFrom.tsx、根目录set-version.ts等源码，说明每个步骤背后的版本管理机制，读完你可以独立完成 Remotion 文档 PR 的版本标注修正。

一、背景：AvailableFrom在 Remotion 文档中的作用

AvailableFrom是 Remotion 文档站点（位于packages/docs）自定义的 MDX 全局组件。它的作用是在文档段落旁渲染一个版本徽标，并指向该版本的 Release 页面，让读者一眼看出"这个功能从 v 多少开始可用"。

组件实现在 AvailableFrom.tsx，关键行为有三点：

1. v属性必填：源码中如果v为空会直接throw new Error('v is required')，意味着文档构建期就能暴露缺失的版本标注；
2. 容忍v前缀：if (v.startsWith('v')) { v = v.slice(1); }，即写v="4.0.469"和v="4.0.469"效果一致；
3. 渲染为 Release 链接：组件最终输出一个<a>，href指向对应 GitHub Release 页面（v${v}形式的 tag 路径），徽标上显示v{v}，鼠标悬停提示Added in v{v}。

该组件通过 Docusaurus 的主题扩展注册为全局 MDX 组件：MDXComponents.js 将AvailableFrom连同MinNodeVersion、MinBunVersion、MinEslintVersion等一并导出，因此任意.mdx文档都可直接使用<AvailableFrom v="..." />，无需 import。仓库中大量文档页面（如packages/docs/docs/animatedimage.mdx、packages/docs/docs/bundle.mdx等）都在用它。

理解了组件的渲染语义后，就能明白版本取值为什么重要：v的值会被直接拼进 Release 链接。如果填了一个尚未发布的版本号，链接指向一个不存在的 tag；如果填了main上已发布的旧版本号，则会误导读者以为该功能是旧版本就有的。

二、为什么是"main版本 + 0.0.1"：Remotion 的版本模型

要理解 update-version 技能的计算规则（main的VERSION加 1 个补丁位），需要先看清 Remotion 仓库的版本管理链条：

1. 版本号的唯一事实来源是packages/core/src/version.ts。

该文件内容非常短（见 version.ts）：

// Automatically generated on publish export const VERSION = '4.0.520';

文件头部注释 "Automatically generated on publish" 说明它不是手工维护的——每次发布时由脚本重新生成。

2. 生成逻辑在packages/core/ensure-correct-version.ts。

ensure-correct-version.ts 会读取packages/core/package.json中的version字段，重新写出src/version.ts，然后执行构建（bun run make与类型检查），并校验dist/esm/version.mjs、dist/cjs/version.js两份产物中都确实包含了新版本号，任何一个缺失都会process.exit(1)。这保证了"package.json、源码常量、构建产物"三处版本严格一致。

3. 发布时由根目录set-version.ts统一抬升所有包。

set-version.ts 是发布脚本（用法bun set-version.mjs 4.0.178），它要求当前在main分支上，遍历packages/下所有含package.json的目录（外加cloudrun/container），把每个应发布包的version写成新版本，随后依次触发 core 与 media-parser 的ensure-correct-version.ts校验、全仓库构建、packages/it-tests的版本一致性测试，最后git add .提交一个v<version>的 commit 并打 tag。

4. 补丁版本递增是 Remotion 的既定发布节奏。

仓库中另一份配套技能 version/SKILL.md 明确了这一前提：

We are working on the next version of Remotion. The current version can be found inpackages/core/src/version.ts.The next version is going to be a patch version.Ensure the docs correctly reference the next version.

即：main上的VERSION是"最近一次已发布"的版本，下一个版本一定是 patch + 1。update-version 技能正是在这个前提下工作的——文档 PR 中新增的AvailableFrom应该指向"即将包含这些改动的那次发布"，也就是main版本 + 0.0.1。

三、操作流程：五步完成 PR 中AvailableFrom的版本更新

以下流程完整继承自 update-version/SKILL.md，适用于"PR 包含packages/docs下的文档改动，其中带有<AvailableFrom v="...">，且取值应反映下一个发布版本"的场景。

步骤 1：获取main分支的规范版本号

git fetch origin main --quiet git --no-pager show origin/main:packages/core/src/version.ts

从输出中读出VERSION常量（例如4.0.468），然后把 patch 位加 1，得到下一个补丁版本（4.0.469）。

两点细节值得注意：

• 使用git show origin/main:...直接读取远端main的文件内容，而不是读本地工作区——你的 PR 分支可能落后于main，本地文件可能过期，必须以远端为准；
• 只读取、不修改version.ts，它由发布流程（set-version.ts→ensure-correct-version.ts）自动维护，文档 PR 不应触碰。

步骤 2：定位当前 PR 改动的AvailableFrom条目

git --no-pager diff origin/main...HEAD -- packages/docs | rg 'AvailableFrom v="'

这条命令有三个精确约束，缺一不可：

• origin/main...HEAD三点 diff 只统计"本 PR 相对main的分叉点"引入的改动，排除main上其他 PR 的变化；
• -- packages/docs把范围限定在文档目录（AvailableFrom只出现在文档源码中）；
• rg 'AvailableFrom v="'只保留含版本标注的行，快速得到待核对清单（含文件路径与行上下文）。

步骤 3：只更新本 PR 触及的AvailableFrom取值

将步骤 2 中列出的条目，其v属性统一改为步骤 1 计算出的下一个补丁版本（如4.0.469）。写法上v="4.0.469"与v="v4.0.469"均可——从 AvailableFrom.tsx 的源码看，组件会自动剥离v前缀。

步骤 4：不要改动 PR diff 之外的AvailableFrom

这是技能文档中明确写出的红线：全仓库有成百上千处AvailableFrom标注（仅packages/docs/docs下的.mdx就有大量命中），其中绝大多数对应的是早已发布的历史功能。它们的v值是"该功能首次可用版本"的准确记录，与当前发布版本无关。只改本 PR diff 中的条目，可以避免一次 PR 引入与主题无关的海量文档噪音，也让 diff 评审聚焦于本次改动。

步骤 5：提交并推送

将更新后的文档改动 commit 并 push 到当前 PR 分支。至此，PR 中新增功能标注的版本号就与"下一个实际会发布的版本号"对齐了；等main合入、执行bun set-version.ts <version>发布时，main上的VERSION正好推进到该值，文档标注随即变为"已发布版本"，Release 链接也真实可达。

四、与发布脚本的联动：版本推进的完整闭环

把 update-version 技能放回整个发布链路中看，它其实是文档侧的一次"预对齐"：

1. 文档 PR 阶段：AvailableFrom标注为main版本 + 0.0.1（本文流程）；
2. 合入main后，正式发布时由 set-version.ts 把所有包的package.json抬升到同一新版本（例如4.0.469），它内部会跳过 featured 模板目录、按shouldReleasePackage策略过滤不需要发布的包（策略来自packages/studio-shared/src/release-package-policy），随后调用ensure-correct-version.ts重建version.ts并校验产物；
3. set-version.ts末尾还会git add . && git commit -m "v<version>"并打 tag——AvailableFrom组件指向的正是这类v<version>tag，形成"文档徽标 → Release tag"的闭环。

换句话说：如果文档 PR 把AvailableFrom写成了main上的旧版本号，发布完成后该徽标会指向一个"早于功能实际可用"的 Release，语义错误且难以追溯；如果写成更大的未来版本，Release 链接在发布时点又暂时 404。"main+ 0.0.1" 恰好是两边都不出错的唯一取值。

五、实践要点小结

• 唯一事实来源：packages/core/src/version.ts的VERSION常量（由 ensure-correct-version.ts 在发布时自动生成），不要手工编辑它；
• 取值公式：下一个补丁版本 =main的VERSIONpatch 位 + 1，前提是 Remotion 当前按 patch 节奏迭代（见 .agents/skills/version/SKILL.md）；
• 改动边界：只改git diff origin/main...HEAD -- packages/docs命中的AvailableFrom v="..."，其余条目一律不动；
• 格式容错：v前缀可加可不加，组件源码会自动剥离；v为空会在渲染/构建时抛错；
• 渲染语义：v值会直接拼进 GitHub Release 链接（见 AvailableFrom.tsx 中href的构造），所以取值必须对应一个真实存在的版本。

这套流程把"文档标注"与"版本发布"两个本来异步的动作精确对齐：文档 PR 提前把版本号预置到下一个补丁版本，发布脚本随后把版本号推到同一值，最终读者在文档中看到的版本徽标与 Release tag 严格一一对应。

【免费下载链接】remotion🎥 Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion