参考
贡献指南
如何为 HyperFrames 做出贡献。
感谢你有兴趣为 HyperFrames 做出贡献！本指南涵盖从环境搭建、运行测试到提交 Pull Request 的所有内容。
快速开始
Fork 并克隆
在 GitHub 上 Fork 仓库，然后克隆你的 Fork：
git clone https://github.com/YOUR_USERNAME/hyperframes.git
cd hyperframes
安装依赖
HyperFrames 使用 bun 进行包管理：
bun install
构建所有包
构建 monorepo 以确保所有代码可以编译：
bun run build
运行 Studio
启动开发服务器以验证你的环境：
bun run dev
如果 Studio 在 http://localhost:3000 打开并显示预览，说明你的环境已准备就绪。
创建分支
为你的工作创建一个特性分支：
git checkout -b my-feature
开发
常用命令
bun install # 安装所有依赖
bun run dev # 启动 Studio（composition 编辑器 + 实时预览）
bun run build # 构建所有包
bun run --filter '*' typecheck # 对所有包进行类型检查
Studio 编辑工作
如果你要修改 Studio 的可视化编辑界面，请在编辑代码前阅读 Studio 手动 DOM 编辑。检查器刻意只暴露它能安全回写到 HTML 的交互，因此修改应保持能力门控、源码补丁模型和已记录的限制。
运行测试
bun run --filter @hyperframes/core test
bun run --filter @hyperframes/engine test
bun run --filter @hyperframes/core test:hyperframe-runtime-ci
cd packages/producer && bun run docker:build:test && bun run docker:test
运行所有测试
bun run --filter '*' test
包
| 包 | 路径 | 描述 |
|---|---|---|
@hyperframes/core | packages/core | 类型定义、HTML 生成、运行时、linter |
@hyperframes/engine | packages/engine | 可寻址的页面到视频捕获引擎 |
@hyperframes/producer | packages/producer | 完整渲染流水线（捕获 + 编码） |
@hyperframes/studio | packages/studio | Composition 编辑器 UI |
hyperframes | packages/cli | 用于创建、预览和渲染的 CLI |
可以做什么
不确定从哪里开始？这里有一些方向：
- 适合新手的 issue —— 在 GitHub 上寻找标记为
good first issue的 issue - 文档 —— 改进文档、添加示例、修复拼写错误
- Linter 规则 —— 添加新规则以捕获更多 composition 错误
- 示例 —— 创建新的入门示例
- Bug 修复 —— 查看 issue 跟踪器中的已报告 bug
Pull Request
提交格式
所有提交和 PR 标题请使用 conventional commit 格式：
feat: add timeline export
fix: resolve seek overflow at composition boundary
docs: add GSAP easing examples
refactor: extract frame buffer pool into shared module
est: add regression test for nested composition timing
CI 要求
以下所有检查必须通过后你的 PR 才能被合并：
- 构建 ——
bun run build成功 - 类型检查 ——
bun run --filter '*' typecheck无错误 - 测试 —— 所有测试套件通过
- 语义化 PR 标题 —— PR 标题遵循 conventional commit 格式
审核流程
- PR 需要至少 1 位维护者的批准
- 保持 PR 聚焦——每个 PR 只包含一个功能或修复
- 仅 alpha 的 PR 请目标设为
next而非main；详见 发布渠道了解分支策略 - 包含清晰的变更描述和原因
- 为新功能和 bug 修复添加测试
报告问题
- 使用 GitHub Issues 提交 bug 报告和功能请求
- 创建新 issue 前请先搜索已有的 issue
- Bug 报告请包含：
- 复现步骤
- 预期行为 vs 实际行为
- HyperFrames 版本（
npx hyperframes info） - 操作系统和 Node.js 版本
社区
- GitHub Issues 报告 bug、请求功能、讨论想法。
- 行为准则 我们的社区标准和期望。
许可证
贡献即表示你同意你的贡献将在 Apache 2.0 许可证 下授权。