mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
JamesandClaude Opus 4.6
98113c2447
- Add READMEs for all 5 packages (core, engine, producer, cli, studio) with install, overview, basic usage, and links to full docs - Rewrite core README from internal doc to OSS-facing format - Polish root README: add badges, packages table, docs link, requirements - Add AI usage policy and BDFL governance statement to CONTRIBUTING.md - Genericize license references (pending final license decision) - Docs URL set to hyperframes.heygen.com Addresses VA-850. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
110 lines
4.3 KiB
Markdown
110 lines
4.3 KiB
Markdown
# Contributing to Hyperframes
|
|
|
|
Thanks for your interest in contributing to Hyperframes! This guide will help you get started.
|
|
|
|
## Getting Started
|
|
|
|
1. Fork the repository
|
|
2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/hyperframes.git`
|
|
3. Install dependencies: `bun install`
|
|
4. Create a branch: `git checkout -b my-feature`
|
|
|
|
## Development
|
|
|
|
```bash
|
|
bun install # Install all dependencies
|
|
bun run dev # Run the studio (composition editor)
|
|
bun run build # Build all packages
|
|
bun run --filter '*' typecheck # Type-check all packages
|
|
bun run lint # Lint all packages
|
|
bun run format:check # Check formatting
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
bun run --filter @hyperframes/core test # Core unit tests (vitest)
|
|
bun run --filter @hyperframes/engine test # Engine unit tests (vitest)
|
|
bun run --filter @hyperframes/core test:hyperframe-runtime-ci # Runtime contract tests
|
|
```
|
|
|
|
### Linting & Formatting
|
|
|
|
```bash
|
|
bun run lint # Run oxlint
|
|
bun run lint:fix # Run oxlint with auto-fix
|
|
bun run format # Format all files with oxfmt
|
|
bun run format:check # Check formatting without writing
|
|
```
|
|
|
|
Git hooks (via [lefthook](https://github.com/evilmartians/lefthook)) run automatically after `bun install` and enforce linting + formatting on staged files before each commit.
|
|
|
|
## Pull Requests
|
|
|
|
- Use [conventional commit](https://www.conventionalcommits.org/) format for **all commits** (e.g., `feat: add timeline export`, `fix: resolve seek overflow`). Enforced by a git hook.
|
|
- CI must pass before merge (build, typecheck, tests, semantic PR title)
|
|
- PRs require at least 1 approval
|
|
|
|
## Packages
|
|
|
|
| Package | Description |
|
|
| ----------------------- | ------------------------------------------- |
|
|
| `@hyperframes/core` | Types, HTML generation, runtime, linter |
|
|
| `@hyperframes/engine` | Seekable page-to-video capture engine |
|
|
| `@hyperframes/producer` | Full rendering pipeline (capture + encode) |
|
|
| `@hyperframes/studio` | Composition editor UI |
|
|
| `hyperframes` | CLI for creating, previewing, and rendering |
|
|
|
|
## Releasing (Maintainers)
|
|
|
|
All packages use **fixed versioning** — every release bumps all packages to the same version.
|
|
|
|
### Via GitHub UI (recommended)
|
|
|
|
1. Go to **Actions** → **Prepare Release** → **Run workflow**
|
|
2. Enter the version (e.g., `0.2.0`)
|
|
3. Click **Run workflow** — this creates a release PR
|
|
4. Review and merge the PR
|
|
5. Merging auto-creates the `v0.2.0` tag, which triggers npm publish and a GitHub Release
|
|
|
|
### Via CLI
|
|
|
|
```bash
|
|
# Bump versions, commit to a branch, create PR
|
|
bun run set-version 0.2.0
|
|
git checkout -b release/v0.2.0
|
|
git add packages/*/package.json
|
|
git commit -m "chore: release v0.2.0"
|
|
git push origin release/v0.2.0
|
|
gh pr create --title "chore: release v0.2.0" --base main
|
|
# After merge, the tag + publish happen automatically
|
|
```
|
|
|
|
## Reporting Issues
|
|
|
|
- Use [GitHub Issues](https://github.com/heygen-com/hyperframes/issues) for bug reports and feature requests
|
|
- Search existing issues before creating a new one
|
|
- Include reproduction steps for bugs
|
|
|
|
## AI-Assisted Contributions
|
|
|
|
We welcome contributions that use AI tools (GitHub Copilot, Claude, ChatGPT, etc.). If you used AI to help write a PR, there is no need to disclose it — we review all code on its merits. However:
|
|
|
|
- You are responsible for the correctness of any code you submit, regardless of how it was generated.
|
|
- AI-generated tests must actually test meaningful behavior, not just assert truthy values.
|
|
- Do not submit AI-generated code you don't understand. If you can't explain what a change does during review, it will be rejected.
|
|
|
|
## Governance
|
|
|
|
Hyperframes uses a **BDFL (Benevolent Dictator for Life)** governance model. The core maintainers at HeyGen have final say on the project's direction, API design, and what gets merged. This keeps the project focused and moving fast.
|
|
|
|
Community input is valued and encouraged — open issues, propose RFCs, and discuss in PRs. But final decisions rest with the maintainers.
|
|
|
|
## Code of Conduct
|
|
|
|
This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions will be licensed under the project's license. See [LICENSE](LICENSE) for details.
|