You will learn#
- the rules that every change must respect;
- where to start reading, and which page covers each step;
- how a contribution reaches a release.
The idea#
Vukem Video is a small, open source (MIT) video editor that people and AI agents operate through one command core. The code, the planning documents and this site live in one repository, AlexGalhardo/vukem-video. The specifications in docs/ are the contract: when code and a specification disagree, one of them is wrong and the pull request fixes it. Everything in the repository is written in English; the documentation also has a Brazilian Portuguese translation.
By taking part you agree to the Code of Conduct. Report a vulnerability privately, as the security policy describes, never in a public issue.
The rules that are never traded#
- One command core. Every editing rule lives in
core/(Go, pure, no I/O). The UI, the MCP server, the CLI and the HTTP API are thin adapters over one service, so a rule about timelines written in a handler or in TypeScript is rejected. - The UI never computes the result of an edit. It draws what the core says and sends commands.
- Names come from one place. Operations, tables, error codes and variables are in the shared definitions (
docs/sdds/000-shared-definitions.md). Change it first. - FFmpeg is a separate LGPL process. Pixels are composed in Go, and nothing GPL ships.
- No outbound network connection by default, no telemetry.
- No new dependency without the maintainer's approval, and versions are exact.
Quick start#
- Set up your machine: Development setup.
- Find your way around: Repository layout.
- Read the requirement and the specification of the area you will touch (
docs/prds/anddocs/sdds/). - Make a small change, with a test, and run the checks.
- Write the commit as in Commits and pull requests.
- If you changed behaviour, update its documentation page: Writing documentation.
A contribution is a branch whose commits the maintainer integrates into the open release branch; open the pull request against release/vX.Y.Z when one is open. The maintainer reviews, fixes the last defects and cuts the release; see The release process.
Common mistakes#
- A change with no test. A fix needs a test that fails without it, and a change to authentication, path handling or the FFmpeg invocation also needs a
Security:footer. - Reporting "it works" without the output of the checks. A report is a claim, not evidence.
- Editing a generated file by hand, such as
core/schema/,site/generated/or the pages undersite/content/generated/. Run the generator. - Adding a dependency in a pull request that did not ask for it.