NIP-34: add PR and PR update events #1966

DanConwayDev · 2025-07-01T12:04:51Z

With the advent of Grasp, we can now do PRs without relying on a single contributor-selected Git server, which they would have to provision and could be rugged at any time.

Note how the commit ID is included in the event and any updates, be it force pushes or additional commits, are added by supplementary PR update events. This ensures history is maintained and Nostr events remain the authority, rather than Git servers.

Grasp servers with proactive sync enabled will copy the commits to ensure that they are available if the contributor-selected Git server is unreliable or removed.

This also provides an alternative for large patches, which are too large to be included within a signle nostr event.

It is also more supported by Git tools which don't always have patch support. For example, isomorphic-git, which enables Git in the browser.

fiatjaf · 2025-07-01T12:17:01Z

Looks good to me.

34.md

TheAwiteb · 2025-07-02T10:51:02Z

LGTM, I like the idea that I can create a PR with and without GRASP server. Make it more flexible.

DanConwayDev · 2025-07-02T15:55:38Z

this last update makes the clone tag required and clarifies what should be listed.

DanConwayDev · 2025-07-02T15:59:24Z

last update adds line:
"Patches SHOULD be used if each event is under 60kb, otherwise PRs SHOULD be used."

Stirfry max event size default is 65kb and nostr-rs-relay is 128kb.

DanConwayDev · 2025-07-02T16:17:48Z

last update handles what SHOULD happen when an additional patch would exceed the 60kb limit. It enables a PR as a patch-revision.

DanConwayDev · 2025-07-02T16:26:36Z

Perhaps we should think about applying nip-22 style threading to Status and Patches as propsed in #1799 ?
At the time I drafted it, I wasn't in favour of merging it as its a breaking change. But here we are already material updates and additions to how changes can be proposed and applied.

DanConwayDev · 2025-07-02T16:26:40Z

@dluvian @Silberengel do you have any thoughts about all this?

dluvian

Having two types increases complexity. If patches only work for <60kB changes and PRs work for any size then I will completely ignore patches and only work with PRs to avoid the complexity of maintaining two types.

dluvian · 2025-07-03T01:24:00Z

34.md

+    ["p", "<repository-owner>"],
+    ["p", "<other-user>"], // optionally send the PR to another user to bring it to their attention


Uppercase P for repo-owner and lowecase p for people directly mentioned in the PR. Repo owner could be in P and p if he was mentioned directly in it. Gives client devs the option to improve notification/inbox filtering

That makes a lot of sense and provides more flexibility. However, an uppercase P is used only for the author of the "root scope event" in NIP-22. Its use for other purposes isn't prohibited in NIP-22, but I haven't seen it used anywhere else. Will we break non-git-specialist clients by doing this? For example, clients may:

Assume there is only one P tag.

Assume it can't be the thread root but get confused as there is no corresponding E tag.

Carry these P tags through to replies.

Isn't a repo the root space of a PR?

Isn't a repo the root space of a PR?

In the context of a PR, Patch or Issue, its important that repo announcement isn't mistaken for the root of the thread. Otherwise a single filter can't be used to find all comments related to that thread.

In the context of a PR, Patch or Issue, its important that repo announcement isn't mistaken for the root of the thread.

Makes sense.

Your suggestion is a really good idea but we need a bit more thought around the above question before adding it to the spec:

Will we break non-git-specialist clients by doing this?

34.md

dluvian · 2025-07-03T01:27:49Z

34.md

+    ["p", "<repository-owner>"],
+    ["p", "<other-user>"], // optionally send the PR to another user to bring it to their attention


Same p and P here

34.md

Silberengel · 2025-07-03T09:21:14Z

We never wanted patches.

TheAwiteb · 2025-07-03T10:11:52Z

@Silberengel wrote in this comment

We never wanted patches.

So why do we use GitViaNostr if it's not for decentralized patches and issues?

TheAwiteb · 2025-07-03T10:21:02Z

@dluvian wrote in this comment

Having two types increases complexity. If patches only work for <60kB changes and PRs work for any size then I will completely ignore patches and only work with PRs to avoid the complexity of maintaining two types.

Is this because of the PR revision of patches? Then what do you think about closing the patch and open a PR if the revision > 60KB?

Silberengel · 2025-07-03T10:26:31Z

So why do we use GitViaNostr if it's not for decentralized patches and issues?

You aren't even using it. You're using GitHub.
Because PRs work.

We tried to use ngit patches, as a team, and the repo quickly turned into 🍝. So, nope.

TheAwiteb · 2025-07-03T10:40:51Z

So why do we use GitViaNostr if it's not for decentralized patches and issues?

You aren't even using it. You're using GitHub. Because PRs work.

We tried to use ngit patches, as a team, and the repo quickly turned into 🍝. So, nope.

You didn't answer my question, anyway, I'm using patches in Nostr and it's good, you just make the patches and send them or fetch them and apply them, I don't know why your repo turned into a spaghetti

Silberengel · 2025-07-03T10:46:29Z

Because the commits were too large.

dluvian · 2025-07-03T10:53:23Z

@dluvian wrote in this comment

Having two types increases complexity. If patches only work for <60kB changes and PRs work for any size then I will completely ignore patches and only work with PRs to avoid the complexity of maintaining two types.

Is this because of the PR revision of patches? Then what do you think about closing the patch and open a PR if the revision > 60KB?

That's still more work than simply ignoring patches and only implementing PRs. I do prefer patches and their simplicity but if their size restriction is a practical issue I would ignore them and only work with PRs

dluvian · 2025-07-03T11:42:45Z

@cypherhoodlum are you still working on a git stuff client? Any thoughts on this?

fiatjaf · 2025-07-03T12:06:56Z

@dluvian wrote in this comment

Having two types increases complexity. If patches only work for <60kB changes and PRs work for any size then I will completely ignore patches and only work with PRs to avoid the complexity of maintaining two types.

Is this because of the PR revision of patches? Then what do you think about closing the patch and open a PR if the revision > 60KB?

That's still more work than simply ignoring patches and only implementing PRs. I do prefer patches and their simplicity but if their size restriction is a practical issue I would ignore them and only work with PRs

Does it make sense to write in the repo announcement that you only accept patches or only PRs or both? Then whatever client/relay the repository owner is choosing can keep that field updated?

Patches are great because they don't require a server, and we cannot guarantee that everybody will have access to a server, even if it's commoditized with GRASP. Servers may still require a setup or registration process in the long run, and for some small things just issuing a "send patch" command from the command line is probably better.

@DanConwayDev what do you think about vastly simplifying the patch flow to make it only use one event, throwaway, very simple and dumb -- and leave any slightly more complicated flow to PRs?

DanConwayDev · 2025-07-03T12:53:29Z

Does it make sense to write in the repo announcement that you only accept patches or only PRs or both? Then whatever client/relay the repository owner is choosing can keep that field updated?

My concern is that repository maintainers won't make a considered or informed choice; instead, a client with an ideological bent for one or the other will choose for them, without the maintainer understanding the implications. imo, this decision shouldn't be made during onboarding, as it assumes too much knowledge and requires too much thought, which would degrade the user experience.

@DanConwayDev what do you think about vastly simplifying the patch flow to make it only use one event, throwaway, very simple and dumb -- and leave any slightly more complicated flow to PRs?

Most of the complexity is optional and degrades gracefully. You would still need status. I think what you are getting at is that support for patch sets isn't really optional. I'm not sure it would be possible to make them optional. Removing them would significantly degrade the usefulness of patches. Most patches sent via email today are part of a patch set.

TheAwiteb · 2025-07-03T13:00:15Z

I think what you are getting at is that support for patch sets isn't really optional. I'm not sure it would be possible to make them optional. Removing them would significantly degrade the usefulness of patches. Most patches sent via email today are part of a patch set.

Also make a set of patches in one single event will make the patches useless, because they will not be accepted by most of the relays because their events are large.

I think the current approach are good, use patches if each commit is less than 60KB otherwise use PRs.

DanConwayDev · 2025-07-04T11:34:19Z

this last update adds tags to README.md as requested in #1966 (comment)

DanConwayDev · 2025-07-04T12:13:32Z

this last update simplies the Patch ~> PR path. I expect this very much to be an edge case.

DanConwayDev · 2025-07-31T08:58:37Z

quick update: I have partially built this into the git remote helper shipped with ngit:

git pushon a branch withpr/prefix will use the PR event style instead of publishing large patches, but right now only if a grasp server is listed as aclone urlin therepository announcement event`.
merge status is automatically issued.
patch ~> PR path is seamlessly handled - patch close status issued; PR created referencing the root patch.
additional git push and git push --force for pr/* branches use the PR update event.

Its available on the main branch of ngit.

It still needs to be integrated into ngit send, ngit list and handle the case where the repository doesn't use any grasp servers or when the grasp servers don't accept the refs/nostr/<event-id> branch.

Further protocol updates are needed:

a grasp server preferences event like 10063 in NIP-B7 (blossom) to know which servers user want to use and have paid for / permission to use.
a repository announcement event flag such as ['t','personal-fork'] to indicate there isn't a "willingness to receive patches, bug reports and comments in general", which publishing an announcement event currently expresses according to the nip. We may want to host a fork as a patched dependancy of another project or use so we can push our own PR data to refs/nostr/<event-id>.

DanConwayDev · 2025-07-31T13:18:44Z

rebased on to master incorporatating NIP-34 tweaks #1998 and #1964

DanConwayDev · 2025-08-07T12:59:41Z

Further protocol updates are needed:

a grasp server preferences event like 10063 in NIP-B7 (blossom) to know which servers user want to use and have paid for / permission to use.

a repository announcement event flag such as ['t','personal-fork'] to indicate there isn't a "willingness to receive patches, bug reports and comments in general", which publishing an announcement event currently expresses according to the nip. We may want to host a fork as a patched dependancy of another project or use so we can push our own PR data to refs/nostr/<event-id>.

I've pushed 1e2fc88 along those lines.

I'm still working through the ngit / git-remote-nostr implementation. There are more failure opportunties when the change is not bundled with the change announcement as with patches.

34.md

TheAwiteb · 2025-08-12T13:23:19Z

34.md

+    ["clone", "<clone-url>", ...] // at least one git clone url where commit can be downloaded
+    ["branch-name", "<branch-name>"] // optional recommended branch name
+
+    ["e", "<root-patch-event-id>"] // optionally indicate PR is a revision of an existing patch, which should be closed


So, when I want to fetch a patch, do I have to check if it's mentioned in a PR to fetch the PR's status? Isn't that complicated? I mean, there's no need to do all of this; we can just close the patch and open a PR. There's no need to check if the PR exists and fetch its status in every patch, right?

Also if there is more than one PR mentioning the same patch, which PR should I fetch its status? It's really complicated.

Knowing that opening a patch and replacing it with a PR later is rare, because I'll know the changes I made before submitting the patch. I don't think there are reviewers who would request changes so numerous that they would require moving the patch to a PR.

I know I've annoyed you with this point, but it really annoys me. Sorry.

Suggested change

["e", "<root-patch-event-id>"] // optionally indicate PR is a revision of an existing patch, which should be closed

DanConwayDev · 2025-08-12T20:23:20Z

You haven't at all annoyed me. If we can make it better we should. We could make it clear that PRs use nip11 threading so 'mentioning' another patch would use a 'q' tag rather than 'e' for a replacement. Your client doesn't have to treat them as one. It can be treated as a closed patch and a newly opened PR with the same title. What do you think?

TheAwiteb · 2025-08-19T11:18:33Z

34.md

 ## Replies

 Replies to either a `kind:1621` (_issue_) or a `kind:1617` (_patch_) event should follow [NIP-22 comment](22.md).



Should we add PR here?

TheAwiteb · 2025-09-03T20:24:02Z

https://n34.dev supports Pull Requests now. 🚀

Support for pull requests, it's not standard in NIPs yet[1] but there must be two clients that support it to be included in NIPs, n34 is one of them. This support: - Create a new PR `n34 pr new` - Update PR tip `n34 pr update` - View a PR `n34 pr view` - List PRs `n34 pr list` - Add `PR` and `PR-update` kinds as roots in `NostrClient::find_root` - Support issuing statuses for PRs - Support GRASP PR and PR-update - Update the docs [1] nostr-protocol/nips#1966

34.md

alexgleason · 2025-10-15T22:13:34Z

Oops, I meant to comment on this PR, not the other. Should this be merged? Looks like we have support from ngit, n34.dev. I am working on implementing into Shakespeare. Anything left to do?

DanConwayDev · 2025-10-16T08:33:55Z

I've now added support in gitworkshop.dev. Based on this experience I'm suggesting two minor tweaks:

Clients SHOULD push to refs/nostr/<[PR|PR-Update]-event-id> for all servers and not just grasp servers. Rationale: a) Clients need to push to some ref so we might as well be consistant. b) Not all git tools (eg isomoprhic git) support fetching by commit-id.
add merge-base tag. Rationale: a) Detect PR Update as a rebase just from the events, no git tooling needed. b) Identify commits in the PR after the fact if merged via a fast-forward merge.

I pushed an update to this NIP branch (commit bf5c2bd) with these tweaks and a few formatting fixes.

ngit has support in the master branch, when this PR is merged I'll issue a release.

ngit-relay (currently the only grasp implementation) support this PR, meaning it will receive commit sent to refs/nostr/<valid-event-id>.

I think we are ready to merge this.

34.md

With the advent of Grasp, we can now do PRs without relying on a single contributor-selected Git server, which they would have to provision and could be rugged at any time. Note how the commit ID is included in the event and any updates, be it force pushes or additional commits, are added by supplementary PR update events. This ensures history is maintained and Nostr events remain the authority, rather than Git servers. Grasp servers with proactive sync enabled will copy the commits to ensure that they are available if the contributor-selected Git server is unreliable or removed. This also provides an alternative for large patches, which are too large to be included within a signle nostr event. It is also more supported by Git tools which don't always have patch support. For example, isomorphic-git, which enables Git in the browser.

reasons for a 'personal-fork' respository include storing PR refs and maintaining a patched version of a dependency. the user grasp list is generally useful by also enables auto-selecting grasp servers for pushing PR refs.

TheAwiteb reviewed Jul 2, 2025

View reviewed changes

34.md Outdated Show resolved Hide resolved

34.md Outdated Show resolved Hide resolved

34.md Outdated Show resolved Hide resolved

TheAwiteb reviewed Jul 2, 2025

View reviewed changes

34.md Outdated Show resolved Hide resolved

DanConwayDev force-pushed the nip34-add-pr branch 2 times, most recently from fd6bc27 to e9073a5 Compare July 2, 2025 08:25

TheAwiteb approved these changes Jul 2, 2025

View reviewed changes

DanConwayDev force-pushed the nip34-add-pr branch from e9073a5 to fadcf2a Compare July 2, 2025 15:54

DanConwayDev force-pushed the nip34-add-pr branch from fadcf2a to b0d94e3 Compare July 2, 2025 15:56

DanConwayDev force-pushed the nip34-add-pr branch from b0d94e3 to 6a7ac11 Compare July 2, 2025 16:17

dluvian reviewed Jul 3, 2025

View reviewed changes

DanConwayDev force-pushed the nip34-add-pr branch from 6a7ac11 to 7468655 Compare July 3, 2025 08:58

DanConwayDev force-pushed the nip34-add-pr branch 2 times, most recently from d28f8c3 to 5599fc4 Compare July 3, 2025 09:33

DanConwayDev force-pushed the nip34-add-pr branch from 3f9d86a to 6ee3532 Compare July 4, 2025 11:59

DanConwayDev force-pushed the nip34-add-pr branch from 6ee3532 to 1e2fc88 Compare July 31, 2025 13:13

DanConwayDev mentioned this pull request Jul 31, 2025

NIP-34: mention marker ~> q tag NIP-10 update #1998

Merged

alltheseas mentioned this pull request Jul 31, 2025

Git on nostr positive interoperability NIP-34 nostrability/nostrability#72

Open

TheAwiteb suggested changes Aug 7, 2025

View reviewed changes

34.md Show resolved Hide resolved

34.md Outdated Show resolved Hide resolved

DanConwayDev force-pushed the nip34-add-pr branch from f1968cf to 84fac7f Compare August 7, 2025 13:48

TheAwiteb suggested changes Aug 12, 2025

View reviewed changes

TheAwiteb approved these changes Aug 13, 2025

View reviewed changes

TheAwiteb reviewed Aug 19, 2025

View reviewed changes

DanConwayDev force-pushed the nip34-add-pr branch from 84fac7f to 790e247 Compare August 19, 2025 12:24

This was referenced Sep 3, 2025

Use nip22 style tags in git statuses #2003

Open

NIP-34: send patches and issues to repos not yet on Nostr #2050

Open

alexgleason reviewed Oct 15, 2025

View reviewed changes

34.md Outdated Show resolved Hide resolved

DanConwayDev force-pushed the nip34-add-pr branch 2 times, most recently from db714cd to b7a9084 Compare October 16, 2025 08:25

TheAwiteb reviewed Oct 16, 2025

View reviewed changes

34.md Outdated Show resolved Hide resolved

DanConwayDev added 2 commits October 16, 2025 14:49

NIP-34: add user grasp list and optional personal-fork ann tag

2aaba90

reasons for a 'personal-fork' respository include storing PR refs and maintaining a patched version of a dependency. the user grasp list is generally useful by also enables auto-selecting grasp servers for pushing PR refs.

DanConwayDev force-pushed the nip34-add-pr branch from b7a9084 to 2aaba90 Compare October 16, 2025 13:49

alexgleason merged commit 6e6b987 into nostr-protocol:master Oct 16, 2025

		["p", "<repository-owner>"],
		["p", "<other-user>"], // optionally send the PR to another user to bring it to their attention

		## Replies

		Replies to either a `kind:1621` (_issue_) or a `kind:1617` (_patch_) event should follow [NIP-22 comment](22.md).

NIP-34: add PR and PR update events #1966

NIP-34: add PR and PR update events #1966

Uh oh!

Conversation

DanConwayDev commented Jul 1, 2025

Uh oh!

fiatjaf commented Jul 1, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TheAwiteb commented Jul 2, 2025

Uh oh!

DanConwayDev commented Jul 2, 2025

Uh oh!

DanConwayDev commented Jul 2, 2025

Uh oh!

DanConwayDev commented Jul 2, 2025

Uh oh!

DanConwayDev commented Jul 2, 2025

Uh oh!

DanConwayDev commented Jul 2, 2025

Uh oh!

dluvian left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Silberengel commented Jul 3, 2025

Uh oh!

TheAwiteb commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TheAwiteb commented Jul 3, 2025

Uh oh!

Silberengel commented Jul 3, 2025

Uh oh!

TheAwiteb commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Silberengel commented Jul 3, 2025

Uh oh!

dluvian commented Jul 3, 2025

Uh oh!

dluvian commented Jul 3, 2025

Uh oh!

fiatjaf commented Jul 3, 2025

Uh oh!

DanConwayDev commented Jul 3, 2025

Uh oh!

TheAwiteb commented Jul 3, 2025

Uh oh!

DanConwayDev commented Jul 4, 2025

Uh oh!

DanConwayDev commented Jul 4, 2025

Uh oh!

DanConwayDev commented Jul 31, 2025

Uh oh!

DanConwayDev commented Jul 31, 2025

Uh oh!

DanConwayDev commented Aug 7, 2025

Uh oh!

Uh oh!

dluvian left a comment •

edited

Loading

TheAwiteb commented Jul 3, 2025 •

edited

Loading

TheAwiteb commented Jul 3, 2025 •

edited

Loading

TheAwiteb Aug 12, 2025 •

edited

Loading

DanConwayDev commented Aug 12, 2025 via email •

edited

Loading