ngit docs

Maintainers ​

A repository's roster says who can push to it, who can manage its issues and pull requests, and who decides that. The everyday commands come first; the rare cases are under Going deeper.

Roles ​

  • Maintainers push branches and tags, and manage issues and pull requests.
  • Moderators manage issues and pull requests, but cannot push.
  • The lead maintainer is the one maintainer who also manages the roster.

How a roster grows ​

A repository starts with a single maintainer. When that maintainer adds someone else, they become the lead maintainer.

Listing someone is an invitation, not an appointment. An invited maintainer or moderator must accept before they are authorised, and until they do their events are not authoritative for the repository.

bash
# Alice invites Bob. Alice becomes the lead maintainer.
ngit repo edit --add-maintainer <bob-npub>

# ngit prompts Bob to accept.
ngit repo accept

# Bob can also host the git data while accepting.
ngit repo accept --grasp-server grasp.example.com

Moderators are invited, accept, and are removed the same way. Leads change the roster one relationship at a time:

bash
ngit repo edit --add-maintainer <npub>
ngit repo edit --remove-maintainer <npub>
ngit repo edit --add-moderator <npub>
ngit repo edit --remove-moderator <npub>

Keeping up with roster changes ​

Each maintainer records the roster history, so after a roster change ngit prompts everyone involved for their step, in this order:

bash
# 1. A newly invited maintainer accepts. This is what authorises them.
ngit repo accept

# 2. The lead records when they accepted in the roster history.
ngit repo edit --acknowledge-maintainer-change <new-npub>

# 3. Every other maintainer follows the lead.
ngit repo follow-lead

Step 2 only updates the accepted timestamp in the history. The new maintainer is authorised as soon as they accept. Because the history is kept, status changes someone made while they held a role stay valid after they leave.

Handing over the lead ​

The incoming lead must already have accepted as an ordinary maintainer. Then, in this order:

bash
# 1. The incoming lead sets themselves as lead.
ngit repo edit --lead-maintainer <own-npub>

# 2. The outgoing lead points at the new lead.
ngit repo edit --lead-maintainer <new-lead-npub>

# 3. Every other maintainer follows the new lead.
ngit repo follow-lead

Between steps 1 and 2 the two announcements disagree about who leads, so the outgoing and incoming lead should coordinate and run their steps in quick succession rather than over a long period.

Leaving ​

Maintainers and moderators can leave without waiting to be removed:

bash
ngit repo leave

Going deeper ​

Maintainers: going deeper covers repositories with no lead, how listing a maintainer also trusts their list, an invitee who already has a repository with the same name, and how to inspect an unusual roster before repairing it.

Next ​