Docs

Contributing

Overview

MachineFabric is a small open project. Three things in the system are community-curated, and each has its own GitHub-issue-driven workflow:

  • Cartridges — packaged executables that provide capabilities. Submitted to cartridge-shelf, reviewed by maintainers, and merged into the canonical cartridge manifest that ships with every MachineFabric install.
  • Capabilities — the named operations cartridges can serve, identified by tagged URNs. Submitted to capfab and published to the CAPDAG registry.
  • Media defs — the typed inputs and outputs capabilities consume and produce, also identified by tagged URNs. Same flow as capabilities; submitted on capfab.

There is no automated merge anywhere in the system. Every submission is read by a human, discussed on the issue, and merged when the maintainers are satisfied. This page explains the cartridge flow in detail; the CAPDAG contributing guide covers the capability and media def flows.

Submitting a cartridge

Submit a Cartridge

You submit a public git URL pointing at the cartridge’s source repository. Anyone can submit a cartridge — yours or someone else’s. The inclusion requirements follow; if you’re unsure about any of them, submit anyway and we’ll work through them with you on the issue.

Inclusion requirements

  • Public repository. Submissions must be publicly accessible without authentication. No private repos, no auth-required URLs, no compressed archives — a real public git URL.
  • .git URL form. The submitted URL must include the protocol (usually https://) and the .git extension, e.g. https://github.com/<owner>/<name>.git.
  • At least one tagged release following semantic versioning. We prefer cartridges that ship signed and notarized .pkg installers, but the minimum is a tag we can point at.
  • Builds and runs on macOS using the standard MachineFabric cartridge tooling. The cartridge can be implemented in any language as long as it produces a single executable that speaks the Bifaci protocol.
  • Valid cap URNs. Every capability the cartridge serves must have a URN that parses with the capdag library, with in and out direction tags that reference media URNs already in the standard registry. If your cartridge needs a capability or media def that doesn’t exist yet, submit those on capfab alongside this submission and we’ll review them together.
  • Behaves on a user’s machine. No data exfiltration, no cryptocurrency mining, no surprise network traffic. We will refuse cartridges that breach this in obvious ways and remove accepted cartridges that turn out to.

What happens next

  1. You open the issue with one or more repository URLs and a sentence per URL explaining what the cartridge does and which cap URNs it serves.
  2. A maintainer opens a PR appending each URL to submitted.txt. The issue stays open while we review — we may ask questions on the issue thread or ask for changes in your repo.
  3. When we’re satisfied, we add the cartridge to the canonical manifest and move the URL from submitted.txt to accepted.txt. The issue is closed with a link to the live entry.
  4. If we decide not to accept a submission, the issue is closed with the reason. The closed issue is the public record — there is no separate rejection list.

Removing a cartridge

Remove a Cartridge

You can request that an accepted cartridge be removed from the manifest. We weigh removals against impact: accepted cartridges are referenced by deployed installs and by users’ saved machine notations, so we work with you on a deprecation path before pulling anything in active use. Removal requests from the cartridge’s own author or maintainer are weighted highest; requests from users come with more scrutiny about whether the cartridge can be repaired instead.

Reporting a vulnerability

Report a Vulnerability

For security issues affecting an accepted cartridge — anything that exfiltrates data, contacts unexpected hosts, or otherwise misbehaves — open the report template. Don’t include working exploits or credentials in a public issue; we’ll arrange a private channel if the issue requires one. We typically pull the cartridge from the manifest while we investigate, then either accept a fixed version or leave it removed.

Bugs, features, and questions

Bug, Feature, or Question

Anything that isn’t a submission, removal, or security report — questions about how the shelf works, suggestions for the submission process, bugs in the listed metadata — goes here. We answer everything we can and update the process when feedback exposes a real friction point.

Where the line lives between cartridge-shelf and capfab

The two repos handle different surfaces:

  • A cartridge is an implementation — a binary you can run that serves one or more capabilities. Submit it on cartridge-shelf.
  • A capability is a named operation — a URN like cap:in="media:pdf";extract;out=media:textable describing what an implementation can do. Submit it on capfab.
  • A media def is a typed payload — a URN like media:pdf describing a kind of input or output. Submit it on capfab.

If you’re submitting a cartridge that serves caps not yet in the registry, you’ll typically open issues on both repos: the capfab issues describe the new caps and media defs, and the cartridge-shelf issue describes the implementation. The maintainers coordinate the two reviews so the cartridge isn’t accepted before the URNs it depends on are.

Code of conduct

Be kind. Be useful. The MachineFabric community is small enough that one bad actor noticeably degrades the experience for everyone. If a maintainer asks you to revise a submission, it’s because we want to merge it.