Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
85 lines (58 loc) · 10.3 KB

CONTRIBUTING.md

File metadata and controls

85 lines (58 loc) · 10.3 KB
Raw

Contributing to Patternflow

Patternflow is a device, a firmware, a website and a pile of documentation, and people contribute to all of them. This page says where each kind of contribution goes, what checks it meets, and the few rules that are not negotiable. Where to ask things is SUPPORT.md; how we treat each other is CODE_OF_CONDUCT.md; what is where is docs/REPOSITORY.md.

Where your contribution goes

You have… It goes in A change touches What CI runs on it
A fix to a guide, a README or a spec the markdown file itself: the root guides, docs/, any folder's README one file every relative link must resolve (docs-links)
A fix to the interactive guide at patternflow.work/guide (Build, Play, Make, Audio) its words are TypeScript, English and Korean side by side: web/src/components/guide/copy.ts for Play, web/src/components/guide/copy/ for Build, Make, Audio and the hub the copy, both languages web-ci
A fix to the breadboard build guide web/src/app/build/breadboard/page.tsx — that guide is React, not markdown JSX text web-ci (next build)
Your finished build, for the build map web/src/components/sections/InsideGlobe/builds.ts plus a photo folder web/public/builds/<slug>/ — see Your build. Not a git person? The Share your build form does the same one Build entry and its photos web-ci (the typecheck rejects a malformed entry)
A firmware feature firmware/patternflow/features/<name>/, plus one line in the bundle it joins (firmware/bundles/<edition>/features_local.h) the folder, the bundle line, an inventory row in features/README.md; a console page also adds a row to firmware/toolchain/console_pages.py; a library also goes in platformio.ini firmware-checks (boundary, ABI freeze, presets, console pages…) and firmware-build (every edition, from scratch)
A fix to the firmware core (patternflow.ino, src/) the file itself — for a bug or a real improvement to the device, never to make room for a feature the same, and the change must still be right on a build that has no features at all
An enclosure or mechanical remix hardware/case/remixes/<maker>-<variant>/, with a README that states Author, License, what it is based on, which board it fits, and the print or cut settings one new folder; the official folders stay as they are the README fields are checked
A bridge to host software (TouchDesigner, Node-RED, Max, a DAW…) integrations/<host>/ with a README, plus a row in integrations/README.md. It talks to the panel through the contracts in docs/ and never imports firmware or web code one new folder the README has to name the contract it is built against
A change to a wire contract docs/rest-api.md, osc-spec.md, midi-spec.md, mqtt-spec.md, audio-ws-spec.md, pfst-v2-spec.md the spec: bump its version line and add a Version history row docs-links
Web app work web/ — start at web/README.md and web/ARCHITECTURE.md web-ci: lint, typecheck, the check:* suites, next build
A pattern not this repository. Make it in the Pattern Lab, press Publish, and it is on the Community for every Patternflow to play, under the license you choose. PATTERN_GUIDE.md walks the loop. The presets bundled in the firmware and the Basics pack are curated by the maintainer from the repository's own sources

Parts sourcing tips, better photos of a build step, a clearer sentence: all of those are the first row.

Sending it

  1. Fork the repository and branch from dev (fix/…, feat/…, docs/…).
  2. Commit with the area first, then a short present-tense summary — see Commit messages.
  3. Open the pull request against main. dev is the maintainer's working branch; outside work is reviewed and merged into main, and main is pulled back into dev afterwards.
  4. Fill in the template: what, why, how you tested it, and which row of the table above it is. The checks in that row run on every pull request, forks included, with no secrets involved.
  5. Nobody pushes to main directly, the maintainer included, so a one-word typo fix is also a pull request. It is a small one.

Before you open a firmware pull request

  • Read, in this order: docs/EDITIONS.md (what a feature and an edition are, and the promises every build keeps) → firmware/patternflow/features/README.md (the hooks) → firmware/bundles/README.md (the two files that make an edition). FEATURE_GUIDE.md is the walk-through, written so an AI coding agent can follow it too.
  • The core names no feature. No #include, no #if PF_<FEATURE>_ENABLED, not even the feature's name in a string on the panel. If your change to src/ would be wrong on a build without your feature, it belongs in features/. firmware/toolchain/check_boundaries.py enforces this in CI.
  • A feature without a bundle line compiles nowhere. Name the edition it joins in the pull request, or propose a new one.
  • Run before pushing: ./firmware/bundles/build.sh all (every edition, and a scan of each image for its feature markers) and python firmware/toolchain/check_boundaries.py. Touching the core means building every composition; the default build has no features to break.
  • Explore in a fork first. Features need room to be wrong for a while. Once it runs on a panel, an in-tree pull request that touches only features/<yours>/ and a bundle line is welcome.

The rules that are not negotiable

The full list, with the reasons, is AGENTS.md — written for AI coding agents, but the rules are the project's, not the agents'. In short:

  • The board has one power input, J4, the screw terminal. Never describe USB-C as a power option; a board powered that way smoked at a connector pin after twenty minutes.
  • hardware/bom/bom_v3.9.csv is the BOM source of truth. The parts table in BUILD_GUIDE.md and hardware/pcb/schematic.pdf must match it; change one, check the other two.
  • Two licenses, strictly split. Code is MIT, hardware and docs are CC BY-SA 4.0, and the SPDX header in a file is the authority where one exists. Don't merge the license files.
  • Brand naming. "Patternflow" in prose, "PATTERNFLOW" engraved on hardware, patternflow in filenames and URLs.
  • The firmware core is not the place to put a feature. See above.

Licensing — inbound = outbound

What you send is licensed the way the place it lands in is licensed: code under MIT, hardware files, guides and docs under CC BY-SA 4.0. You keep your copyright and your name; the project gets the right to bundle and redistribute. There is no CLA. Code files carry an SPDX line (and an // Author: line if it is yours); a remix folder or a bridge states its license in its README, because STL and DXF files cannot carry a header. The whole table is docs/LICENSE-SUMMARY.md.

Patterns published to the Community are a different thing: you pick their license when you publish (CC BY-SA 4.0 by default, or CC BY 4.0), and nothing on this page applies to them.

Commit messages

Start with the area, then a short summary in plain present tense.

area: short summary

web: collapse the preset list on mobile
firmware: fix reversed encoder direction
docs: clarify the breadboard wiring step
hardware: knob plate for 18 mm shafts
integrations: node-red example flow

Use wip(area): … for work that isn't finished yet. Nothing enforces this; it keeps the history and the Discord dev-log readable.

Your build

A pin on the map is one entry in web/src/components/sections/InsideGlobe/builds.ts and a folder of photos in web/public/builds/<slug>/. The type at the top of that file documents every field; the comments next to the fields say how precise a location to give and what a collaboration is. The slug becomes the pin's URL (/inside/<slug>), so pick it once. Photos you add are CC BY-SA 4.0 unless the entry says otherwise. If you would rather not touch the file, the Share your build form asks for the same things and the maintainer files it.

Adding an Inside entry

Inside includes builds, projects derived from Patternflow, and places where it is used. Add one entry to web/src/components/sections/InsideGlobe/builds.ts: a short title, maker, public location, date, description, and any external links. Photos are optional. Keep existing id and slug values stable so shared links keep working.

Choose one primary category: builds for assembled devices and enclosure changes, projects for ports and new tools, or in-use for installations, performances and other uses. This is separate from kind, which preserves the existing build/collaboration relationship and marker style. A maker can have several entries: a new tool and a later exhibition are different records. Link to the maker's own documentation for ongoing updates; a short introduction here is enough. Do not add unannounced work or assume an event happened from a sale or a planned appearance.

Classify the subject of the entry, not its surroundings. A completed device photographed in a studio or DJ booth is still a builds entry. Use in-use when the entry documents actual use in an exhibition, performance or installation; a sale or delivery alone is not enough. Leave a category empty until a qualifying case is available.

How the maintainer works

The dev → main routine, release cutting and what the workflows attach live in docs/RELEASING.md. Governance is one person: the maintainer decides what merges, in the open, in the pull request. Two collaborators have write access to the areas they built.