Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

NIP-34: Git Remote Nostr URL format and helper spec #1624

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

NIP-34: Git Remote Nostr URL format and helper spec #1624

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 51 additions & 7 deletions 34.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
NIP-34
======
# NIP-34

`git` stuff
-----------
## `git` stuff

`draft` `optional`

Expand Down Expand Up @@ -96,6 +94,9 @@ The first patch revision in a patch revision SHOULD include a NIP-10 `e` `reply`
["parent-commit", "<parent-commit-id>"],
["commit-pgp-sig", "-----BEGIN PGP SIGNATURE-----..."], // empty string for unsigned commit
["committer", "<name>", "<email>", "<timestamp>", "<timezone offset in minutes>"],

["branch-name", "<custom-branch-name>"], // optional short name for use by git-remote-nostr
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this just an implementation detail of git-remote-nostr? If yes then maybe we shouldn't include it here.


]
}
```
Expand All @@ -104,7 +105,7 @@ The first patch in a series MAY be a cover letter in the format produced by `git

## 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.
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.

Issues may have a `subject` tag, which clients can utilize to display a header. Additionally, one or more `t` tags may be included to provide labels for the issue.

Expand Down Expand Up @@ -136,9 +137,9 @@ Replies are also Markdown text. The difference is that they MUST be issued as re

// 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"],
["e", "<previous-reply-id-hex>", "", "reply"]
// rest of tags...
],
]
// other fields...
}
```
Expand Down Expand Up @@ -181,6 +182,49 @@ The Status event with the largest created_at date is valid.

The Status of a patch-revision defaults to either that of the root-patch, or `1632` (Closed) if the root-patch's Status is `1631` and the patch-revision isn't tagged in the `1631` event.

## Git client nostr plugin (git-remote-nostr)

Definition: Clone URL - a git remote URL listed under the `clone` tag of the repositories kind `30617` event

The offical git client supports interacting with 'remotes' using custom protocols via [git-remote-helpers](https://git-scm.com/docs/gitremote-helpers).

An implementation of git-remote-nostr SHOULD:

### 1. Use Git Remote Nostr URL Format

Struture:

- `nostr://` - git syntax for a protocol URL
- `<user>@` - optional ssh user for interacting with Clone URLs
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It can possibly be the NIP-05 user, too

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess overriding ssh user is not possible if using NIP-05 in the url.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It can possibly be the NIP-05 user, too

that is covered in line 202 and 203.

- `<protocol>/` - optional prefered protocol for interacting with Clone URLs. eg. ssh or https
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this needs some further explanation, what is an example scenario, why the protocol in the clone URL is not enough.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it enables maintainers to push to git servers using specific ssh keys or over authenticated http. It came out of discussion on this ngit issue.

ngit has since been updated to largely ignore the protocol listed in the clone tag and instead silently try protocols until it succeeds and record when a non-default one works best.
This nostr url remains the only way however to specify a non-default ssh user key.

How much context do you think I need to include in the nip?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

now I realize it's totally offtopic to the PR. Lets discuss in chat group. I have additional questions, but dont want to block this.

- kind `30617` event coordinate in format:
- `<naddr>`
- `<npub|nip05-address>/<identifier>`
- `<npub|nip05-address>/<relay-hint*>/<identifier>`

\*relay hints SHOULD be [URL encoded](https://www.w3.org/Addressing/URL/4_Recommentations.html) eg `ws%3A%2F%2Funencrypted.com` and may omit `wss://` for brevity and readability.

for example `nostr://[email protected]/ngit` or `nostr://npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/relay.damus.io/ngit`

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it should be mandatory to use nip05 relays if somebody wants to use their nip05 in a git remote url. It should throw error if either:

  • there are no nip05 relays and no relay hint in the url
  • the repo event is not found on any of the nip05 or hint relays
    But I have no strong opinions on this. It's possible to use the bootstrap/fallback relays to find the repo (30617) event.

Anyway it should be clear that the NIP-05 relays or the hint relays are used to find the repo event, which contains the repo relays. All subsequent operations go to the repo relays.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good clients that show the nostr git url should include a relay hint inline if the announcement event isn't on, at least one of, the nip05 relays. this should be a client implementation detail.

### 2. Manage state on nostr and access objects via Clone URLs

Store and retrieve state in the `30618` event and git objects in the Clone URLs. Proxy state updates to each Clone URLs.

If a `30618` cannot be found or git config item `nostr.nostate` is `true`, use state from the first Clone URL.

### 3. Use `pr/*` branch namespace for 'Open' patches
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would mention how to browse the draft PRs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this remote helper spec doesn't support it. The guidance here is to use other tools eg ngit. I'm not sure the mention of a specific client like ngit is appropriate for inclusion in a NIP.


Each 'Open' patch / patch set on repository relays SHOULD be have a corresponding branch in the format:

`pr/<branch-name*>(<first-8-chars-of-hex-root-patch-event-id)`

A branch pushed in the format `pr/<branch-name>` should be published as a:

- patch / patch set, if there is no upstream branch
- patch revision, if there is a upstream branch with conflicts
- as additional patches in the set, if there is an upstream branch without conflicts

\*`<branch-name>` is the first 60 chars of root event `branch-name` tag if present, or the commit subject, with invalid chars replaced with `-`.

## Possible things to be added later

Expand Down