hyperframes/CONTRIBUTING.md

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: pnpm install
4. Create a branch: git checkout -b my-feature

Development

pnpm install        # Install all dependencies
pnpm dev            # Run the studio (composition editor)
pnpm build          # Build all packages
pnpm -r typecheck   # Type-check all packages

Running Tests

pnpm --filter @hyperframes/core test          # Core unit tests (vitest)
pnpm --filter @hyperframes/engine test        # Engine unit tests (vitest)
pnpm --filter @hyperframes/core test:hyperframe-runtime-ci  # Runtime contract tests

Pull Requests

• Use conventional commit format for PR titles (e.g., feat: add timeline export, fix: resolve seek overflow)
• 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.

Steps

# 1. Bump version, commit, and tag
pnpm set-version 0.1.1 --tag

# 2. Push to trigger the publish workflow
git push origin main --tags

The v* tag triggers CI, which validates (build + typecheck + tests) then publishes all packages to npm with provenance attestation.

Without --tag (manual control)

# 1. Bump versions only (no commit/tag)
pnpm set-version 0.1.1

# 2. Review changes, commit yourself
git add -A
git commit -m "chore: release v0.1.1"
git tag v0.1.1
git push origin main --tags

Reporting Issues

• Use GitHub Issues for bug reports and feature requests
• Search existing issues before creating a new one
• Include reproduction steps for bugs

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

License

By contributing, you agree that your contributions will be licensed under the MIT License.