FabricLoom documentation

Contributing

How cartridges and definitions get into MachineFabric

In this section

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 are packaged executables that provide capabilities. They are submitted to cartridge-shelf, reviewed by maintainers, and merged into the canonical cartridge manifest that ships with every MachineFabric install.
  • Capabilities are the named operations cartridges can serve, identified by tagged URNs. They are submitted to capfab and published to the CapDAG registry.
  • Media defs are the typed inputs and outputs capabilities consume and produce, also identified by tagged URNs. They follow the same flow as capabilities and are submitted on capfab.

Nothing in the system is merged automatically. A human reads every submission, discusses it on the issue, and merges it 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, whether it is their own or someone else’s. The inclusion requirements follow. If you are unsure about any of them, submit anyway and we will work through them with you on the issue.

Inclusion requirements

  • Public repository. Submissions must be publicly accessible without authentication. Private repos, URLs that require authentication, and compressed archives are not accepted. The URL must be a real public git URL.
  • .git URL form. The submitted URL must include the protocol (usually https://) and the .git extension, for example 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 CapDAG 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 does not exist yet, submit it on capfab alongside this submission and we will review them together.
  • Behaves on a user’s machine. No data exfiltration, no cryptocurrency mining, and no unexpected network traffic. We refuse cartridges that clearly breach this 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 during review. We may ask questions on the issue thread or ask for changes in your repo.
  3. When we are 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, and 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 their impact. Accepted cartridges are referenced by deployed installs and by users’ saved machine notations, so we work with you on a deprecation path before removing anything in active use. Removal requests from the cartridge’s own author or maintainer carry the most weight. Requests from users get closer scrutiny about whether the cartridge can be repaired instead.

Reporting a vulnerability

Report a vulnerability

For security issues affecting an accepted cartridge, such as data exfiltration, contact with unexpected hosts, or other misbehavior, open the report template. Do not include working exploits or credentials in a public issue. We will arrange a private channel if the issue requires one. We typically pull the cartridge from the manifest during the investigation, then either accept a fixed version or leave it removed.

Bugs, features, and questions

Bug, feature, or question

Anything that is not a submission, removal, or security report goes here. This includes questions about how the shelf works, suggestions for the submission process, and bugs in the listed metadata.

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 such as cap:in="media:document;ext=pdf";extract;out=media:enc=utf-8 describing what an implementation can do. Submit it on capfab.
  • A media def is a typed payload: a URN such as media:document;ext=pdf describing a kind of input or output. Submit it on capfab.

A cartridge that serves caps not yet in the registry typically needs 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 is not accepted before the URNs it depends on.

Code of conduct

Be kind and useful. If a maintainer asks you to revise a submission, it is because we want to merge it.