Skip to content

Contributing

Contributing guide

How to take part in Vukem Video: the rules that are not traded, where to start and how a change reaches a release.

Last updated:

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#

  1. 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.
  2. The UI never computes the result of an edit. It draws what the core says and sends commands.
  3. 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.
  4. FFmpeg is a separate LGPL process. Pixels are composed in Go, and nothing GPL ships.
  5. No outbound network connection by default, no telemetry.
  6. No new dependency without the maintainer's approval, and versions are exact.

Quick start#

  1. Set up your machine: Development setup.
  2. Find your way around: Repository layout.
  3. Read the requirement and the specification of the area you will touch (docs/prds/ and docs/sdds/).
  4. Make a small change, with a test, and run the checks.
  5. Write the commit as in Commits and pull requests.
  6. 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 under site/content/generated/. Run the generator.
  • Adding a dependency in a pull request that did not ask for it.

Next steps#