Skip to content

docs: CONTRIBUTING is generic and says nothing about how this device is built #10

Description

@c0remusic

The problem

.github/CONTRIBUTING.md is the generic template: fork, branch, small commits, open a
pull request. It contains nothing specific to this project.

A Max for Live device has real constraints that a contributor cannot guess and will hit on
their first attempt:

  • which JavaScript dialect the device code must stay within, and why;
  • which files are the source of truth versus generated;
  • the ordering constraint between the engine tables and the UI tables (a positional index
    is sent between them, so a one-line shift silently breaks everything downstream);
  • how to build and test a change without the full authoring environment;
  • what a pull request is expected to include as evidence that it works.

Why it matters

The repository already has issue templates, a code of conduct, a security policy and a CI
workflow — the outer shell is in place. The one file that would actually let someone
contribute is the one that says the least.

Without it, either nobody contributes, or the first pull request breaks a constraint
nobody wrote down, which is worse for both sides.

Definition of done

CONTRIBUTING.md states, in plain terms:

  • the language and runtime constraints of the device code;
  • the source-of-truth files and what must never be edited by hand;
  • the index-ordering constraint, spelled out with the consequence of getting it wrong;
  • how to run and test a change locally;
  • what a pull request should contain.

Someone who has never opened the project should be able to make a one-line change and know
whether it worked.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationhelp wantedExtra attention is needed

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions