nostr-protocol · fiatjaf · Mar 5, 2024 · Jan 21, 2024 · Jan 21, 2024 · Jan 21, 2024
diff --git a/34.md b/34.md
@@ -0,0 +1,102 @@
+NIP-34
+======
+
+`git` stuff
+-----------
+
+`draft` `optional`
+
+This NIP defines all the ways code collaboration using and adjacent to [`git`](https://git-scm.com/) 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.
+
+```jsonc
+{
+  "kind": 30617,
+  "content": "",
+  "tags": [
+    ["d", "<repo-id>"],
-    ["d", "<repo-id>"],
+    ["d", "<repo-id>"], // the earliest unique commit id. usually the root commit id unless it's a fork.
-    ["d", "<repo-id>"],
+    ["d", "<repo-id>"], // the earliest unique commit id. usually the root commit id unless it's a fork.
+    ["r", "<repo-id>"],
+    ["r", "<first-commit-id>"], // if the first commit id isn't the earliest unique commit.
-    ["d", "<repo-id>"],
+    ["d", "<repo-id>"], // the earliest unique commit id. usually the root commit id unless it's a fork.
-    ["d", "<repo-id>"],
+    ["d", "<repo-id>"], // the earliest unique commit id. usually the root commit id unless it's a fork.
+    ["r", "<repo-id>"],
+    ["r", "<first-commit-id>"], // if the first commit id isn't the earliest unique commit.
+    ["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
+  ]
+}
+```
+
+The tags `web`, `clone`, `relays` 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.
+
+```jsonc
+{
+  "kind": 1617,
+  "content": "<patch>", // contents of <git format-patch>
+  "tags": [
+    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
-    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
+    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"],
+    ["r", "<repository-unique-reference>"], // the earliest unique commit id. usually the root commit id unless it's a fork.
-    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
+    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"],
+    ["r", "<repository-unique-reference>"], // the earliest unique commit id. usually the root commit id unless it's a fork.
+    ["p", "<repository-owner>"],
+    ["p", "<other-user>"], // optionally send the patch to another user to bring it to their attention
+
+    // for the first patch in a thread or series
+    ["t", "root"],
+
+    // 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>"],
+    ["parent-commit", "<parent-commit-id>"],
+    ["commit-pgp-sig", "-----BEGIN PGP SIGNATURE-----..."], // empty string for unsigned commit
+    ["committer", "<name>", "<email>", "<timestamp>", "<timezone offset in minutes>"],
+  ]
-  ]
+    // if first patch in patch set with no cover_letter
+    ["t", "root"], // if first version
+    ["t", "root-version"], // if first additional version
+    ["e", "<id-of-root-of-previous-version", "mention"], // if first additional version
+    // else
+    ["e", "<id-of-root-patch-or-cover-letter", "root"], // this may be a root-version
+    ["e", "<id-of-[previous-patch-in-set]-or-for-first-[cover-letter]", "reply"],
+ ]
-  ]
+    // if first patch in patch set with no cover_letter
+    ["t", "root"], // if first version
+    ["t", "root-version"], // if first additional version
+    ["e", "<id-of-root-of-previous-version", "mention"], // if first additional version
+    // else
+    ["e", "<id-of-root-patch-or-cover-letter", "root"], // this may be a root-version
+    ["e", "<id-of-[previous-patch-in-set]-or-for-first-[cover-letter]", "reply"],
+ ]
+}
+```
+
+## 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.
+
+```jsonc
+{
+  "kind": 1621,
+  "content": "<markdown text>",
+  "tags": [
+    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
-    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
+    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
+    ["r", "<repository-unique-reference>"], // the earliest unique commit id. usually the root commit id unless it's a fork.
-    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
+    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
+    ["r", "<repository-unique-reference>"], // the earliest unique commit id. usually the root commit id unless it's a fork.
+    ["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.
+
+```jsonc
+{
+  "kind": 1622,
+  "content": "<markdown text>",
+  "tags": [
+    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"],
-    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"],
+    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"],
+    ["r", "<repository-unique-reference>"], // the earliest unique commit id. usually the root commit id unless it's a fork.
-    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"],
+    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"],
+    ["r", "<repository-unique-reference>"], // the earliest unique commit id. usually the root commit id unless it's a fork.
+    ["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"],
+    // ...
+  ]
+}
+```
+
-
+## Pull Requests
+{
+    "kind": 1623
+    "content": ""
+    "tags": [
+        ["commit": "<sha1-commit-hash>"], //MUST
+        ["web": "url where the repo can be viewed"], //OPTIONAL
+        ["git": "url of standard git API"], //MUST
+        ["p": "maintainer(s) pubkey"], //OPTIONAL
+        ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"] //MUST
+      ]
+}
-
+## Pull Requests
+{
+    "kind": 1623
+    "content": ""
+    "tags": [
+        ["commit": "<sha1-commit-hash>"], //MUST
+        ["web": "url where the repo can be viewed"], //OPTIONAL
+        ["git": "url of standard git API"], //MUST
+        ["p": "maintainer(s) pubkey"], //OPTIONAL
+        ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"] //MUST
+      ]
+}
+## 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)