reya/n34
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: support pull requests

Browse Source 
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] https://github.com/nostr-protocol/nips/pull/1966
This commit is contained in:
Awiteb
2025-09-12 06:43:23 +00:00
parent cc3aed0e89
commit 4360aa192c
43 changed files with 1714 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/pr/README.md Normal file
View File

@@ -0,0 +1,43 @@
# Pull Request Management
Pull requests are a new addition to [NIP-34], proposed by [DanConwayDev] in
[nostr-protocol/nips#1966]. The concept is straightforward: it involves an event
that notifies you of changes on a Git server, which can be any Git server. This
event contains two key pieces of information, the Git repository URL and the
commit tip. You can add this remote to your project, check out the specified
commit, and then review or merge/rebase the changes as needed. Additionally,
there is a `PR-update` event that informs you when the previous commit tip is no
longer the head of the changes, such as when new changes are added or a rebase
occurs.
## Why Use the Commit Tip?
Using the commit tip is preferable to relying on a branch name. A branch name
simply points to a commit, so checking out a branch is effectively the same
as checking out a specific commit. However, if we use the branch name instead
of the commit, the changes can be altered by anyone, not just the pull request
author. By checking out a specific commit ID, we ensure that the changes are
exactly as intended by the pull request author and have not been tampered with
by a malicious party.
## Does `n34` Handle Git Operations?
No, `n34` does not perform any Git operations. You can use the `n34 pr view`
command to retrieve the pull request clone URL and the commit tip, allowing
you to fetch the changes manually. Similarly, `n34 pr new` and `n34 pr update`
do not interact with Git directly. They only prompt you for the clone URL and
commit tip to construct the event. For more details on the philosophy behind
`n34`, refer to the [Philosophy] section.
## Why use pull requests instead of patches?
Pull requests are useful for large changes. Most relays limit events to 60KB,
so if your changes exceed that limit (per event, not in total), consider using
pull requests. For [GRASP] servers, the limit is usually higher. Before using pull
requests, check the relays, patches are more decentralized.
[NIP-34]: https://github.com/nostr-protocol/nips/blob/master/34.md
[DanConwayDev]: https://danconwaydev.com
[nostr-protocol/nips#1966]: https://github.com/nostr-protocol/nips/pull/1966
[Philosophy]: https://n34.dev/commands.html#philosophy
[GRASP]: https://ngit.dev/grasp

24
docs/pr/apply.md Normal file
View File

@@ -0,0 +1,24 @@
# Mark as Applied
> `n34 pr apply` command
**Usage:**
```
Usage: n34 pr apply [OPTIONS] <PR_ID> <APPLIED_COMMITS>...
Arguments:
<PR_ID> The open PR id to apply it
<APPLIED_COMMITS>... The applied commits
Options:
--repo <NADDR-NIP05-OR-SET> Repository addresses
```
Creates a kind `1631` event (Applied/Merged status) for the specified PR. The PR
must be in open status.
The `APPLIED_COMMITS` field serves to inform clients about the status of
specific commits, whether they have been applied or not. If you need to retrieve
the list of commits from a specific point (such as the tip of the master branch)
up to the `HEAD`, you can use the following Git command: `git log --pretty=%H
'origin/master..HEAD'`.

18
docs/pr/close.md Normal file
View File

@@ -0,0 +1,18 @@
# Close a Pull Request
> `n34 pr close` command
**Usage:**
```
Usage: n34 pr close [OPTIONS] <PR_ID>
Arguments:
<PR_ID> The open/draft PR id to close it
Options:
--repo <NADDR-NIP05-OR-SET> Repository addresses
```
Issue a kind `1632` (Close status) for the specified PR. The PR have to be open
or drafted.

17
docs/pr/draft.md Normal file
View File

@@ -0,0 +1,17 @@
# Convert to Draft
> `n34 pr draft` command
**Usage:**
```
Usage: n34 pr draft [OPTIONS] <PR_ID>
Arguments:
<PR_ID> The open PR id to draft it
Options:
--repo <NADDR-NIP05-OR-SET> Repository addresses
```
Issue a kind `1633` (Draft status) for the specified PR. The PR have to
be open.

17
docs/pr/list.md Normal file
View File

@@ -0,0 +1,17 @@
# List Pull Requests
> `n34 pr list` command
**Usage:**
```
Usage: n34 pr list [OPTIONS] [NADDR-NIP05-OR-SET]...
Arguments:
[NADDR-NIP05-OR-SET]... Repository addresses
Options:
--limit <LIMIT> Maximum number of patches to list [default: 15]
```
List the repositories pull requests. By default `n34` will look for
`nostr-address` file and extract the repositories from it.

22
docs/pr/merge.md Normal file
View File

@@ -0,0 +1,22 @@
# Merge a Pull Request
> `n34 pr merge` command
**Usage:**
```
Usage: n34 pr merge [OPTIONS] <PR_ID> <MERGE_COMMIT>
Arguments:
<PR_ID> The open PR id to merge it
<MERGE_COMMIT> The merge commit id
Options:
--repo <NADDR-NIP05-OR-SET> Repository addresses
```
Creates a kind `1631` event (Applied/Merged status) for the specified PR. The
PR must be in open status.
You can get the `MERGE_COMMIT` commit using `git rev-parse HEAD` command if
the merge commit in the `HEAD` or use `HEAD~n` where the `n` is the number of
commits the merge commit before the HEAD

30
docs/pr/new.md Normal file
View File

@@ -0,0 +1,30 @@
# Create a Pull Request
> `n34 pr new` command
**Usage:**
```
Usage: n34 pr new [OPTIONS] <--subject <SUBJECT>|--editor> <COMMIT> <CLONES>...
Arguments:
<COMMIT> The SHA-1 hash of the commit at the tip of the PR branch
<CLONES>... Repositories to clone for the pull request, separated by commas
Options:
--repo <NADDR-NIP05-OR-SET> Repository addresses
--body <BODY> The body content of the pull request. Cannot be used together with the `--editor` flag
--subject <SUBJECT> The subject or title of the pull request. Cannot be used together with the `--editor` flag
-e, --editor Opens the user's default editor to write PR subject and body
--labels <LABELS> Labels to associate with the pull request, separated by commas
--branch <BRANCH> The branch name for the pull request
--grasp Push the pull request to the repository GRASP server
```
Submit a pull request to the repositories specified using the `--repo` option or
obtained from the `nostr-address` file.
Utilize the `--grasp` option if you intend to send the pull request to the
[GRASP] servers. Note that `n34` will not automatically send the pull request
for you but will indicate where to push your changes.
[GRASP]: https://ngit.dev/grasp

17
docs/pr/reopen.md Normal file
View File

@@ -0,0 +1,17 @@
# Reopen a Pull Request
> `n34 pr reopen` command
**Usage:**
```
Usage: n34 pr reopen [OPTIONS] <PR_ID>
Arguments:
<PR_ID> The closed/drafted patch id to reopen it
Options:
--repo <NADDR-NIP05-OR-SET> Repository addresses
```
Issue a kind `1630` (Open status) for the specified PR. The PR have to
be closed or drafted.

25
docs/pr/update.md Normal file
View File

@@ -0,0 +1,25 @@
# Update a Pull Request
> `n34 pr update` command
**Usage:**
```
Usage: n34 pr update [OPTIONS] <EVENT-ID> <COMMIT> <CLONES>...
Arguments:
<EVENT-ID> Original PR ID
<COMMIT> The SHA-1 hash of the commit at the tip of the PR branch
<CLONES>... Repositories to clone for the pull request, separated by commas
Options:
--repo <NADDR-NIP05-OR-SET> Repository addresses
--grasp Push the pull request update to the repository GRASP server
```
Update an existing pull request with the new changes.
Utilize the `--grasp` option if you intend to send the pull request to the
[GRASP] servers. Note that `n34` will not automatically send the pull request
for you but will indicate where to push your changes.
[GRASP]: https://ngit.dev/grasp

18
docs/pr/view.md Normal file
View File

@@ -0,0 +1,18 @@
# View a Pull Request
> `n34 pr view` command
**Usage:**
```
Usage: n34 pr view [OPTIONS] <EVENT-ID>
Arguments:
<EVENT-ID> Pull request ID
Options:
--repo <NADDR-NIP05-OR-SET> Repository addresses
```
View a specific pull request. This includes the pull request title, labels,
description, clone URLs, and the latest commit tip. Use this information to
fetch the changes.