Listing a plugin on dev3d.net

This page is about this website: claiming a listing, shipping a version, and getting it through review. For how the artifact itself works — what a bundle contains, how the checksum and the catalog entry fit together, and the rules a host applies when upgrading — read Publishing to the marketplace first and come back.

Two things travel together

• a listing — an id, a name, a description, a category. This is what a person browses.
• a version — a .tar.gz of your plugin directory containing a plugin.json, plus a sha256 of those exact bytes.

They are separate because they change at different rates. The listing is edited in a form; a version is built by your own tooling. A dev3d host only ever acts on the second: it fetches the archive, verifies the checksum against the catalog, and reads the manifest inside.

Step one: claim a listing

Sign in and open Publishing. Create a listing and choose a plugin id.

The id is lowercase reverse-dns with at least one dot — yourname.your-plugin. The dot is not decoration: dev3d namespaces everything a plugin contributes by its id, so yourname.your-plugin registering a tool called echo becomes yourname_your_plugin_echo and cannot collide with anyone else's. An id without a namespace separator is refused before it reaches the catalog.

The id cannot be changed later. Every installation that already has your plugin matches on it.

Step two: ship a version

Two ways, producing the same thing. The archive rules are the same either way, and are set out in full under Publishing to the marketplace.

Upload a bundle

Build a .tar.gz of your plugin directory and upload it. It is inspected before a byte is stored: unsafe paths, links, device nodes, oversized archives, a missing or invalid plugin.json, a manifest whose id disagrees with the listing, and a version that already exists are all refused, each with the reason. The bytes that end up in storage are the bytes that were hashed, so the sha256 the catalog advertises is the sha256 a host will verify.

Connect a GitHub repository

If your releases already live on GitHub, point the listing at the repository instead of uploading by hand. Each tagged release becomes a version.

1. Set the tag prefix — v matches v1.2.0 and v2.0.0-rc.1, but not vendor-tools.
2. Add an access token only if the repository is private, or to raise GitHub's anonymous rate limit. It is stored encrypted and is never shown again.
3. Press Sync releases.

A sync imports the newest few releases each press, because it runs inside a request and cannot import a hundred archives at once. Press it again for more; releases already imported are never re-done.

The version that ships is not taken from the tag. A tag may be v1.2.0, release-1.2.0 or nightly; the version is whatever plugin.json inside the archive says, because that is what a dev3d host matches on. The tag prefix only decides which releases are worth downloading.

A repository archive is accepted as it comes from GitHub, including the layout where the plugin directory sits beside the repository's LICENSE and VERSION. Those sidecar files are ignored and reported rather than silently dropped.

Step three: review

Every version a publisher submits enters a review queue, and nothing reaches /marketplace/catalog.json until a person approves it. Until then it is invisible to installs — including at its own bundle URL, so guessing a filename is not a way around the queue.

A reviewer sees your submission with the manifest's own declarations — what it contributes and which permissions it asks for — because that, not the listing text, is what a host will act on. Approving the first version of a draft listing also publishes the listing.

A rejection comes with a note, and the note is required rather than optional: a rejection you cannot act on would only produce the same submission again.

Two shortcuts exist, and only an administrator can grant either:

• Verified — this account is who it claims to be. It is the badge on your plugin page. It is about identity, not quality.
• Trusted — your submissions skip the queue. This is a genuine reduction in oversight, so it is a separate switch rather than something verification quietly grants.

There is no self-service form to request verification yet; ask through contact.

Publishing from CI

If you would rather not use the web form, mint an API token and publish over HTTP. See Publishing from CI.

Withdrawing

You can withdraw a version you no longer want. An approved version is yanked rather than deleted — it leaves the catalog and stops being served, while the row survives so the download history it explains is not orphaned. A version still awaiting review is deleted outright.

The last approved version of a published listing cannot be withdrawn, because that would leave a catalog entry pointing at a bundle that is gone. Upload a replacement first.