Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
210 lines (151 loc) · 8.67 KB

CONTRIBUTING.md

File metadata and controls

210 lines (151 loc) · 8.67 KB
Raw

Contributing to Beam

This document explains how to contribute to Beam, either using an AI assistant in autonomous mode or following the manual step-by-step developer guide.

Original contributions are licensed under MPL-2.0, as described in Beam licensing. You retain your copyright. Preserve third-party notices and identify imported material and its original license; do not apply Beam's license to assets or code you cannot license.

🤖 AI Assistant Prompt (Copy & Paste)

Copy and paste the prompt below directly into your AI coding assistant (Cursor, Claude Code, Antigravity, Copilot Workspace, etc.) to set up and develop autonomously:

You are an autonomous senior software engineer working on Beam (https://github.com/BeamRecorder/Beam).

Follow these exact steps to prepare your workspace, fork the repository, and deliver changes:

1. **GitHub CLI & Authentication**:
   - Ensure the GitHub CLI (`gh`) is available (https://cli.github.com/).
   - Check authentication status using `gh auth status`. If not authenticated, prompt the user or run `gh auth login`.

2. **Fork & Clone**:
   - Fork and clone the upstream repository:
     `gh repo fork BeamRecorder/Beam --clone`
   - Enter the cloned directory:
     `cd Beam`

3. **Branch Convention**:
   - Create and checkout a dedicated branch based on the goal:
     - Features: `feat/<short-descriptive-name>`
     - Fixes: `fix/<short-descriptive-name>`
     - Performance: `perf/<short-descriptive-name>`
     - Refactoring: `refactor/<short-descriptive-name>`
     - Documentation: `docs/<short-descriptive-name>`
       Example: `git checkout -b feat/custom-watermark`

4. **Engineering Guidelines**:
   - Before making any code changes, read the contracts:
     - `AGENTS.md` & `docs/ARCHITECTURE.md` (Electron security boundary & Rust capture engine)
     - `docs/UI.md` (Design tokens, reusable components in `apps/desktop/src/components/ui/`, no `:deep` overrides)
     - `docs/CODE_QUALITY.md` (Max 500 lines per file, types in dedicated files, small units)
     - `docs/electron_window.md` (Mandatory before touching window sizes, transparent regions, or IPC)

5. **Environment & Dependencies**:
   - Run `bun install` to install frontend & Electron packages.
   - If the user does not have Rust installed, you can still launch the app with `bun run dev`, but the Rust capture engine will never be rebuilded (and will be downloaded via Internet).
   - Verify Rust toolchain availability (`cargo --version`). Refer to `docs/dev/INSTALL_RUST.md` if Rust is missing.

6. **Development & Verification**:
   - Run localized/targeted tests for changed code:
     - Vue/TypeScript: `bunx vitest run <path-to-test>`
     - Electron/Node: `node --test <path-to-test>`
     - Typecheck: `bunx vue-tsc --noEmit`
   - Run `bun run build` to validate end-to-end compilation before submitting.

7. **Submitting Changes**:
   - Use conventional commit messages (`feat: ...`, `fix: ...`, `refactor: ...`).
   - Push your branch and open a PR:
     `git push -u origin <branch-name>`
     `gh pr create --fill`

📖 Developer Guide (Manual Setup)

1. Prerequisites

Make sure you have the following installed on your machine:

OS-specific setup instructions:

2. Forking and Cloning the Repository

  1. Authenticate with GitHub CLI:

    gh auth login

  2. Fork and clone Beam:

    gh repo fork BeamRecorder/Beam --clone
cd Beam

3. Branch Naming Conventions

Always create a new branch from main for your work. Use standard semantic prefixes:

Type Prefix Example
New Feature feat/ feat/export-gif-format
Bug Fix fix/ fix/timeline-snap-alignment
Performance perf/ perf/waveform-decoding
Refactoring refactor/ refactor/audio-engine
Documentation docs/ docs/contributing-guide 
git checkout -b feat/your-feature-name

4. Installing Dependencies & Running Locally

  1. Install Bun dependencies:

    bun install

  2. Start Development Environment:

    bun run dev

    This compiles the Rust native capture addon and starts both Vite and Electron in development mode.

    Each worktree has a separate persistent development profile. Vite automatically selects an available port, and every Electron window connects to that worktree's server. Run the same command in another worktree to test both apps in parallel.

    For multiple profiles within one worktree:

    bun run dev --session first
bun run dev --session second

    Session names use 1–40 lowercase letters, digits, underscores or hyphens, starting with a letter or digit. Restarting the same worktree/session reuses its data. A second launch of the same profile activates its existing Beam window; use a different session name to open another instance.

    Development profiles live under <appData>/Beam Development/<worktree-hash>-<session>/ and isolate Chromium state only. Preferences, presets, video projects, screenshots and imported media stay in the usual Videos/Beam/user/ library, shared with other development sessions and the installed application. Changes and deletions in that library affect every instance. Native builds reuse Cargo's configured target directory, including CARGO_TARGET_DIR and shared caches, without a per-worktree override. Cargo rebuilds only what has changed. Each Electron launch uses a private temporary copy of the engine and Linux helper under node_modules/.cache/beam-native/, removed after that process closes. Named sessions also use separate Vite caches.

    Ctrl+C stops Electron and Vite together. Closing Beam normally also stops its Vite server. Without Cargo, the existing verified download prompt applies; use --force-no-rust to select cached/downloaded binaries even when Cargo is installed.

    Global shortcuts belong to the desktop: an accelerator already registered by another Beam instance cannot be registered again. Use each instance's controls for parallel tests. Development instances do not rewrite GNOME's shared custom shortcut settings.

    For renderer-only browser development, use bun run dev:renderer. The separate bun run electron:dev command remains available; set BEAM_DEV_SERVER_URL to the renderer's local HTTP origin if it is not http://localhost:6500, and use the same --session name when relaunching that profile.

5. Repository Guidelines & Code Quality Contracts

Before contributing, make sure your code aligns with our architecture and style rules:

  • UI Primitives: Always reuse existing UI components from apps/desktop/src/components/ui/ (Button, Select, Popover, Dialog, Slider, Switch, Badge, CopyButton, DeleteItem, etc.). Do not write ad-hoc styled buttons or custom controls.
  • No :deep CSS Selectors: Avoid :deep selectors in scoped Vue component styles.
  • File Length: No single source file should exceed 500 lines. Split larger files into focused composables, modules, or sub-components.
  • Type Definitions: Place shared TypeScript interfaces and types in dedicated .ts files (e.g. *-types.ts), not inside Vue components.
  • Electron Windows: When working on transparent windows, sizes, or shadows, adhere strictly to docs/electron_window.md.

6. Testing & Validation

Run focused tests directly related to the code you modified:

  • Vue / Frontend tests: 
    bunx vitest run apps/desktop/src/components/editor/timeline/tests/
  • Electron / Node tests: 
    node --test test/editor-window.test.cjs
  • Type Checking: 
    bunx vue-tsc --noEmit
  • Production Build Validation: 
    bun run build

7. Submitting a Pull Request

  1. Commit your changes using Conventional Commits:

    git add .
git commit -m "feat(timeline): add multi-track snapping guides"

  2. Push to your fork:

    git push -u origin feat/your-feature-name

  3. Create the Pull Request:

    gh pr create --title "feat: multi-track snapping guides" --body "Detailed summary of changes..."