nostr/nips

mirror of https://github.com/nostr-protocol/nips.git synced 2024-09-05 21:03:47 +00:00

DanConwayDev 8225a018c7 NIP-34: optional tags to improve discoverability

earliest-unique-commit r tag enables clients to:
 - retrieve all repo events refering to a local git repo
 - group repo events with different identifers that refer to same repo
 - retrieve all patches for a local repo,
   irespective of the tagged repo event

current-commit-id r tag enables clients to prevent accidental submission of a patch,
which has already been proposed

root-revision tag enables clients to filter out proposal revisions
from a list of proposals

2024-04-17 17:46:34 -03:00

4.5 KiB

Raw Blame History

NIP-34

`git` stuff

draft optional

This NIP defines all the ways code collaboration using and adjacent to git can be done using Nostr.

Repository announcements

Git repositories are hosted in Git-enabled servers, but their existence can be announced using Nostr events, as well as their willingness to receive patches, bug reports and comments in general.

{
  "kind": 30617,
  "content": "",
  "tags": [
    ["d", "<repo-id>"], // usually kebab-case short name
    ["name", "<human-readable project name>"],
    ["description", "brief human-readable project description>"],
    ["web", "<url for browsing>", ...], // a webpage url, if the git server being used provides such a thing
    ["clone", "<url for git-cloning>", ...], // a url to be given to `git clone` so anyone can clone it
    ["relays", "<relay-url>", ...] // relays that this repository will monitor for patches and issues
    ["earliest-unique-commit", "<commit-id>"] // usually root commit but a recent commit for forks
    ["r", "<earliest-unique-commit-id>"] // so clients can subscribe to all events related to a local git repo
    ["maintainers", "<other-recognized-maintainer>", ...]
  ]
}

The tags web, clone, relays, maintainers can have multiple values.

Except d, all tags are optional.

Patches

Patches can be sent by anyone to any repository. Patches to a specific repository SHOULD be sent to the relays specified in that repository's announcement event's "relays" tag. Patch events SHOULD include an a tag pointing to that repository's announcement address.

Patches in a patch set SHOULD include a NIP-10 e reply tag pointing to the previous patch.

The first patch revision in a patch revision SHOULD include a NIP-10 e reply to the original root patch.

{
  "kind": 1617,
  "content": "<patch>", // contents of <git format-patch>
  "tags": [
    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
    ["r", "<earliest-unique-commit-id-of-repo>"] // so clients can subscribe to all patches sent to a local git repo
    ["p", "<repository-owner>"],
    ["p", "<other-user>"], // optionally send the patch to another user to bring it to their attention

    ["t", "root"], // ommited for additional patches in a series
    // for the first patch in a revision
    ["t", "root-revision"],

    // optional tags for when it is desirable that the merged patch has a stable commit id
    // these fields are necessary for ensuring that the commit resulting from applying a patch
    // has the same id as it had in the proposer's machine -- all these tags can be omitted
    // if the maintainer doesn't care about these things
    ["commit", "<current-commit-id>"],
    ["r", "<current-commit-id>"] // so clients can find existing patches for a specific commit
    ["parent-commit", "<parent-commit-id>"],
    ["commit-pgp-sig", "-----BEGIN PGP SIGNATURE-----..."], // empty string for unsigned commit
    ["committer", "<name>", "<email>", "<timestamp>", "<timezone offset in minutes>"],
  ]
}

Issues

Issues are Markdown text that is just human-readable conversational threads related to the repository: bug reports, feature requests, questions or comments of any kind. Like patches, these SHOULD be sent to the relays specified in that repository's announcement event's "relays" tag.

{
  "kind": 1621,
  "content": "<markdown text>",
  "tags": [
    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
    ["p", "<repository-owner>"]
  ]
}

Replies

Replies are also Markdown text. The difference is that they MUST be issued as replies to either a kind:1621 issue or a kind:1617 patch event. The threading of replies and patches should follow NIP-10 rules.

{
  "kind": 1622,
  "content": "<markdown text>",
  "tags": [
    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"],
    ["e", "<issue-or-patch-id-hex>", "", "root"],

    // other "e" and "p" tags should be applied here when necessary, following the threading rules of NIP-10
    ["p", "<patch-author-pubkey-hex>", "", "mention"],
    ["e", "<previous-reply-id-hex>", "", "reply"],
    // ...
  ]
}

Possible things to be added later

"status" kind (for letting people know a patch was merged or an issue was fixed or won't be fixed)
"branch merge" kind (specifying a URL from where to fetch the branch to be merged)
"cover letter" kind (to which multiple patches can refer and serve as a unifying layer to them)
inline file comments kind (we probably need one for patches and a different one for merged files)

4.5 KiB Raw Blame History