Skip to content

contributing.mdx

Latest commit

 

History

History
162 lines (130 loc) · 5.06 KB

contributing.mdx

File metadata and controls

162 lines (130 loc) · 5.06 KB
title Contributing
description How to contribute to Hyperframes.

Thanks for your interest in contributing to Hyperframes! This guide covers everything you need to get set up, run tests, and submit a pull request.

Getting Started

Fork the repository on GitHub, then clone your fork: ```bash git clone https://github.com/YOUR_USERNAME/hyperframes.git cd hyperframes ``` Hyperframes uses [bun](https://bun.sh/) for package management: ```bash bun install ``` Build the monorepo to ensure everything compiles: ```bash bun run build ``` Start the development server to verify your setup: ```bash bun run dev ``` If the studio opens at `http://localhost:3000` with a preview, your environment is ready. Create a feature branch for your work: ```bash git checkout -b my-feature ```

Development

Common Commands

bun install                          # Install all dependencies
bun run dev                          # Start the studio (composition editor + live preview)
bun run build                        # Build all packages
bun run --filter '*' typecheck       # Type-check all packages

Studio Editing Work

If you are changing Studio's visual editing surface, read Studio Manual DOM Editing before editing code. The inspector intentionally exposes only interactions it can persist safely back to HTML, so changes should preserve the capability gates, source patching model, and documented limitations.

Running Tests

```bash Core bun run --filter @hyperframes/core test ``` ```bash Engine bun run --filter @hyperframes/engine test ``` ```bash Runtime Contract bun run --filter @hyperframes/core test:hyperframe-runtime-ci ``` ```bash Producer (Docker) cd packages/producer && bun run docker:build:test && bun run docker:test ```

Running All Tests

bun run --filter '*' test

Packages

Package Path Description
@hyperframes/core packages/core Types, HTML generation, runtime, linter
@hyperframes/engine packages/engine Seekable page-to-video capture engine
@hyperframes/producer packages/producer Full rendering pipeline (capture + encode)
@hyperframes/studio packages/studio Composition editor UI
hyperframes packages/cli CLI for creating, previewing, and rendering

What to Work On

Not sure where to start? Here are some ideas:

  • Good first issues — look for issues labeled good first issue on GitHub
  • Documentation — improve docs, add examples, fix typos
  • Linter rules — add new rules to catch more composition mistakes
  • Examples — create new starter examples
  • Bug fixes — check the issue tracker for reported bugs

Pull Requests

Commit Format

Use conventional commit format for all commits and PR titles:

feat: add timeline export
fix: resolve seek overflow at composition boundary
docs: add GSAP easing examples
refactor: extract frame buffer pool into shared module
test: add regression test for nested composition timing

CI Requirements

All of the following must pass before your PR can be merged:

  • Build — bun run build succeeds
  • Type check — bun run --filter '*' typecheck reports no errors
  • Tests — all test suites pass
  • Semantic PR title — PR title follows conventional commit format

Review Process

  • PRs require at least 1 approval from a maintainer
  • Keep PRs focused — one feature or fix per PR
  • Target alpha-only PRs at next instead of main; see Release channels for branch policy details
  • Include a clear description of what changed and why
  • Add tests for new features and bug fixes

Reporting Issues

  • Use GitHub Issues for bug reports and feature requests
  • Search existing issues before creating a new one
  • For bug reports, include:
    • Steps to reproduce
    • Expected behavior vs. actual behavior
    • Hyperframes version (npx hyperframes info)
    • Operating system and Node.js version

Community

Report bugs, request features, and discuss ideas. Our community standards and expectations.

License

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