Contributing

English · 中文

Thanks for helping. CONTRIBUTING.md (in Chinese) is the authority; this page is the short version. The same rules apply to people and to coding agents, with a few extra ones for agents.

Two kinds of contribution

• Using the harness, that is, making videos. Your projects live in projects/ and are never committed. What you can give back: a finished film for showcase/, a breakdown for cases/, a shot recipe for recipes/, a general lesson for playbook/ or a type doc's checks.
• Changing the harness: bin/vh, tools/, engines, docs, styles. That goes through a pull request.

The workflow

1. Branch. One topic per branch and per PR. People name branches <name>/<topic>; agents use claude/<topic> or codex/<topic>. Nobody pushes to main, the maintainer included; the main-via-pr ruleset enforces it.
2. Check before you push. tools/ci.sh --committed checks your committed HEAD in a clean checkout, exactly what CI will see. On a Mac, VH_BASH=/bin/bash tools/ci.sh also runs the checks under the system bash 3.2.
3. Open a draft PR. Say what changed, why, and how you verified it. For a bug fix, reproduce it first and show before and after.
4. Merge. After a person has looked, the draft becomes a ready PR and is squash-merged once both CI checks (Linux, macOS) pass, the branch is up to date with main, and review threads are resolved. Auto-merge can do the waiting.
5. Don't rewrite pushed history. No rebase, amend or force-push on a branch you've pushed; merge main into your branch instead.

Along the way:

• For anything users will notice, add a line under Unreleased in CHANGELOG.md.
• If you edit CLAUDE.md, run bin/vh sync-agents to regenerate AGENTS.md; CI checks that the two match.
• Never commit API keys, LOCAL.md, projects/ or render output. If a test re-rendered a tracked swatch in styles/<slug>/media/, restore it before pushing.

Agents also follow a few stricter rules: they push only their own branch, never touch tags, always open drafts, and merge only when a person explicitly asks.

Proposing a style

Follow the six steps in styles/README.md ("加一个新风格"): break down 1–3 works with playbook/07; write STYLE.md (from _TEMPLATE.md) and tokens.json; write swatch.js from the demo (or a Blender scene, swatch.py, when the style needs path-traced light and real depth of field; tabletop-miniature is the example), plus score.json for sound; iterate with bin/vh style <slug> --draft --hud, then render with bin/vh style <slug>; run bin/vh style check <slug>; rebuild the gallery with bin/vh style gallery --mp4 and add a row to the table. Keep to the library's rules: learn the grammar without copying works, treat cultural subjects accurately, use local fonts only. Write the preset as a reference a concept can borrow from, not as a template. A .py that imports bpy carries a GPL-3.0-or-later SPDX header; CI checks the header and runs on every Blender scene the same static scan the renderer runs before Blender starts. A lighter template and review process for community styles is planned for v0.3 (Roadmap).

Proposing a shot recipe

A recipe says how one shot or seam moves: phases in frames, a parameter table with the critical values marked, pitfalls, the frames to check, and a canvas sketch that a style's tokens can skin. Copy recipes/_TEMPLATE.md, fill it in, add it to the index in recipes/README.md and run bin/vh recipes check; CI runs it too. Mark the status honestly: a recipe is battle-tested only when a film made in this repo used it and a person judged the result. If you adapt someone else's recipe, name the source, say what you changed, and keep their licence notice (the Apache-2.0 ones are listed in recipes/NOTICE.md).

Proposing a case study

Break the film down with playbook/07-reverse-engineer.md: get frames, take it apart layer by layer, reverse-engineer the brief, and write it up like the existing cases (what it did, how it was made, why it works, what to borrow). Add it as a file in cases/ and a row in cases/README.md. Respect the platform's terms and the film's copyright when you grab frames: the breakdown is for learning, so don't republish the original's frames. Note the source's license.

Sharing a film

Add a folder to showcase/, named like the existing ones, with BRIEF.md, STORYBOARD.md, NOTES.md, LESSONS.md, the source and a README in the same shape as the others. The video goes into the media release rather than git: upload it with gh release upload media <file> and add its path and sha256 to tools/media.txt (see CONTRIBUTING.md).

Ideas for a first contribution

These aren't filed as issues yet; open one before you start so work isn't duplicated.

• Cut a real talking-head film with the experimental type 09, import the result into an editor, and say where its thresholds and rules were wrong: it has only been calibrated on synthetic material.
• Run the smoke-test items still open in engines/blender.md and write the results back: EEVEE's memory over a 300-frame command-line render, Cycles determinism on Metal (-f N against -a, adaptive sampling on and off), OIDN flicker on still areas, rigid-body caches rendered out of order, whether HyperFrames' <video> keeps alpha, and the guide's own commands on 5.2. Blender 5.2.2 has run the rest.
• Run the dashscope or elevenlabs voice against the live API and report what breaks (you need your own key).
• Install on your Linux distribution and report or fix the rough edges.
• Translate one workflow doc (a type doc or a playbook page) into English.
• Write a case study of a public film made with code.
• Pick an item from the "已知局限" (known limitations) list in playbook/04 and propose a fix.

Questions, bugs and proposals go to issues.