Maintain a listing

For: plugin authors.

Update maintainers, ownership, names and signed releases.

Co-maintain, hand over or move a plugin

A listed name has one publisher, who answers for every version, and as many maintainers as you like. Co-maintain with members: each maintainer has their own account and their own signing key, and nobody shares a private key.

A key added or removed by the publisher's own account, a member, or a statement signed by a key the hub already has for you is continuity: your listings are not flagged.

A key set replaced with nothing signed by a key the hub knows is a change of hands for every listing of the publisher, and a revoked key never comes back.

Every listed version carries its custody: the publisher, the repository and its owner, since when, and the review of the last change of hands, with an epoch that goes up by one at each change. Servers keep the custody their tenants installed, and an update into another epoch waits for a tenant admin's approval on every server (see updates from new hands). Plan a hand-over with that in mind: your users will be asked.

• Hand over within your name (a repository transferred to an organisation, a company that takes over the domain): open a pull request from your account. It gets the change-of-hands review, and the next version's custody epoch goes up.
• Move to another name: one pull request adds the new listing with moved_from and sets moved_to on the old one, and both publishers tie themselves to it. It takes the change-of-hands review and a move review, and the new listing's first version is reviewed like a first plugin. The plugin's name after the slash stays the same. The old listing stays, with its versions; you may deprecate them with a reason. Tenants follow the move only when an admin asks (oz0 plugin update <name> --follow-move).
• Abandoned plugins are never handed to someone else, and a name is never given out again. Fork it under your own name instead. Plugins of the project's own namespace never move out of it.

To tie a change to your publisher without opening the pull request from its account, sign a statement with a key the hub already has for you: the hub repository's hubtool statement writes one (add-key, remove-key, revoke-key, or move to tie your publisher to a move), and you commit it with the change. A maintainer approves each new key set once, in your publisher file. To retire a key that leaked, sign a revoke-key statement with that key and remove it in the same pull request; a key that revoked itself is refused for any publisher from then on.

On our hub a move goes to a name never listed before, the old listing takes no new versions once it moved, and a published move stays. A member speaks for your publisher once the pull request that adds them has merged, not in that pull request, and a statement counts only when it is signed by a key the hub had already published for you. Versions from new hands go above the newest published version: custody follows version order.

A company that runs its own index gets custody from oz0 index sign: each version without custody gets one, from its publisher, repository and owner, with the epoch going up wherever they differ from the previous version's. A plugin that moved states moved_to and its new listing moved_from; index sign refuses a move stated on one side only, one to another name after the slash, one to a plugin the index does not list, and cycles. Custody you write yourself is kept, as long as its epoch never falls and new hands come with a new epoch.

New versions from signed tags

Add --track tags to your first submission, or track: tags to your listing file. The hub's bot then looks for release tags (v1.2.3) newer than your newest listed version and signed by your key:

git -c gpg.format=ssh -c user.signingkey=~/.ssh/id_ed25519 tag -s v1.2.1 -m "github-tools 1.2.1"
git push --tags

It opens one pull request per plugin and never merges it: a maintainer reviews and merges it like any other. When nothing but the version changed (the same publisher, permissions and dependencies as your newest active version) and the hub's checks find nothing, it labels the pull request trivial, so the review is quick. A release with more changes gets a full review, and so does every release while a version of the plugin is quarantined. After the merge, the index lists the version once a waiting period of 72 hours has passed.

Unsigned tags are skipped, and a tag that moves to another commit is reported: the listing keeps the commit it pinned.

Reference

plugin inspect --files <dir> writes the inspected files out as well, which is how the hub's scanners read exactly the bytes they listed.