mirror of
https://github.com/nostr-protocol/nips.git
synced 2024-11-12 23:19:08 -05:00
initial nip17 code collaboration draft
This commit is contained in:
DanConwayDev
parent
a56d1c2877
commit
7db287c1b4
179
17.md
Normal file
179
17.md
Normal file
|
|
@ -0,0 +1,179 @@
|
||||||
|
NIP-17
|
||||||
|
======
|
||||||
|
|
||||||
|
Code Collaboration
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
`draft` `optional` `author:DanConwayDev`
|
||||||
|
|
||||||
|
This NIP sets out an interoperable standard for code collaboration over nostr supporting two models:
|
||||||
|
|
||||||
|
1. __Collaboration Only__: a centralized git server acts as the source of truth and nostr events are used to exchange patches and track and discuss pull requests and issues.
|
||||||
|
1. simple tooling on a developer's workstation supports the generation and application of nostr patches.
|
||||||
|
|
||||||
|
1. __Full Fidelity__: nostr events act as the definitive source of truth for the status of a repository. Commits and merges are not authorized unless they correspond to nostr events signed by repository maintainers.
|
||||||
|
1. tooling on a developer's workstation supports both the generation and validation of events every time a change is pushed or pulled.
|
||||||
|
1. specialist relays run git servers that only accept changes that correspond with authorized nostr events. This reduces the chances of git servers and events from going out of sync.
|
||||||
|
1. web clients can offer a rich UX including the latest repository status without having to synchronize with a git server.
|
||||||
|
1. trust minimized relationship with git servers. Multiple servers can be used for redundancy and provide user choice. In some cases the repository can be interacted with entirely over nostr events without using a git server.
|
||||||
|
|
||||||
|
Clients that support the 'Full Fideilty' model SHOULD support Pull Requests created using the reduced 'Collaboration Only' feature set also.
|
||||||
|
|
||||||
|
### Core Events
|
||||||
|
| kind | name |
|
||||||
|
| ------- | ------------ |
|
||||||
|
| `30017` | Repository |
|
||||||
|
| `17` | Commit |
|
||||||
|
| `1` | Pull Request |
|
||||||
|
| `1` | Code Comment |
|
||||||
|
| `1` | Issue |
|
||||||
|
|
||||||
|
### Full Fidelity Events
|
||||||
|
|
||||||
|
| kind | name |
|
||||||
|
| ------- | ------------ |
|
||||||
|
| `317` | Branch |
|
||||||
|
| `117` | Merge |
|
||||||
|
| `417` | Tag |
|
||||||
|
|
||||||
|
|
||||||
|
### Repository
|
||||||
|
|
||||||
|
A `kind 30017` parameterized replaceable event used as a unique reference and to store associated settings.
|
||||||
|
|
||||||
|
#### Tags
|
||||||
|
|
||||||
|
| Required | Description | Format |
|
||||||
|
| -------- | ------------------------------------------ | ---------- |
|
||||||
|
| X | name | `["d","name..."]` |
|
||||||
|
| | description | `["description","description..."]` |
|
||||||
|
| | full-fidelity flag | `["t", "full-fidelity"]` |
|
||||||
|
| strongly suggested but only required if `full-fidelity` flag is not set | git server reference(s)* | `["r","URI of git repository"]` |
|
||||||
|
| | additional maintainers* | `["p","pubkey"]` |
|
||||||
|
| | relays | `["relays", ...["wss://relay1.com", "wss://relay2.com"]]` |
|
||||||
|
|
||||||
|
\*use multiple tags to reference multiple entities
|
||||||
|
|
||||||
|
`content` SHOULD equal `""`
|
||||||
|
|
||||||
|
### Commit / Patch
|
||||||
|
|
||||||
|
Depending on the presence of a referenced Branch, the `kind 17` event either:
|
||||||
|
|
||||||
|
1. acts as a proposed patch ready to be referenced in a Pull Request; or
|
||||||
|
|
||||||
|
1. signifies the commit referenced within is the head of the branch at the timestamp specified in `created_at`. But only if the authoring pubkey is the branch creator or a repository maintainer, as defined by the Repository event.
|
||||||
|
|
||||||
|
The event `content` MUST either contain the commit patch, mirroring the format produced by `git format-patch`, or equal `""`, in which case the event is considered a 'stub'.
|
||||||
|
|
||||||
|
Clients SHOULD assumed that the commit content of a `kind 17` 'stub' is available via the git server specified in the Repository event unless a NIP-94 event is tagged that contains a file following the patch format.
|
||||||
|
|
||||||
|
Stubs MUST be used for large patches and COULD be used for smaller ones. TODO: Clearer guidance required on use of stubs.
|
||||||
|
|
||||||
|
#### Tags
|
||||||
|
|
||||||
|
| Required | Description | Format |
|
||||||
|
| -------- | ------------------------------------------ | ---------- |
|
||||||
|
| X | repository | `["a", "30017:<pubkey>:<d-identifier>", "<relay url>"]` |
|
||||||
|
| X | commit id | `["c","commit id (SHA-1 hash)"]` |
|
||||||
|
| X | parent commit id or hashtag to indicate first commit | `["parent-commit-id","commit id (SHA-1 hash)"]` or `["t","initial-commit"]`
|
||||||
|
| | commit message | `["commit-message", "content of commit message"]` |
|
||||||
|
| | committer details if they differ from the author details* | `["committer-details", "Tom Smith <tom.smith@example.com>", "Sun, 21 May 2023 06:44:20 +0000"]` |
|
||||||
|
| | NIP-94 event referencing patch file (stub only) | `["e","nip-94_event_id"]` |
|
||||||
|
| | Branch event id (`full-fidelity` model only) | `["e","branch_id"]` |
|
||||||
|
| | Pull Request event id (for `collaboration-only` model only and if the commit is an update to a pre-existing Pull Request) | `["e","branch_id"]` |
|
||||||
|
|
||||||
|
\* This enables commits from patches to retain their commit id when merged. Clients SHOULD assume that the committer details are identical to the author details unless specified or the commit id produced doesnt match.
|
||||||
|
|
||||||
|
### Pull Request
|
||||||
|
|
||||||
|
Pull Requests are `kind 1` events with `content` beginning `NEW PULL REQUEST\n`, followed by a description.
|
||||||
|
|
||||||
|
#### Tags
|
||||||
|
|
||||||
|
| Required | Description | Format |
|
||||||
|
| -------- | ------------------------------------------ | ---------- |
|
||||||
|
| X | Hashtag to identify as Pull Request | `["t","code-pr"]` |
|
||||||
|
| X | title | `["title","insert title..."]` |
|
||||||
|
| X | repository | `["a", "30017:<pubkey>:<d-identifier>", "<relay url>"]` |
|
||||||
|
| | commit id(s) that have existing and corresponding Commit / Patch events that represent the propose change | `["c","commit id (SHA-1 hash)"]` |
|
||||||
|
| | branch to be merged into (`full-fidelity` model only) | `["e","branch_id"]` |
|
||||||
|
| required if branch to be merged into is specified | branch to be merged from (`full-fidelity` model only) | `["from-branch","branch_id"]` |
|
||||||
|
| | additional hashtags as required | `["t","feature"]` |
|
||||||
|
|
||||||
|
TODO: status updates
|
||||||
|
|
||||||
|
### Code Comments
|
||||||
|
|
||||||
|
Tag standards for referencing specific lines of code.
|
||||||
|
|
||||||
|
#### Tags
|
||||||
|
|
||||||
|
| Required | Description | Format |
|
||||||
|
| -------- | ------------------------------------------ | ---------- |
|
||||||
|
| X | hashtag to identify as Comment on Line | `["t","code-comment-on-line"]` |
|
||||||
|
| X | reference to specific line using a tuple | `["r","commit id:file name:line number"]` |
|
||||||
|
| X | repository | `["a", "30017:<pubkey>:<d-identifier>", "<relay url>"]` |
|
||||||
|
| X | searchable reference to the commit | `["c","commit id (SHA-1 hash)"]` |
|
||||||
|
| | branch which the commit is on (`full-fidelity` model only) | `["e","branch_id"]` |
|
||||||
|
| | Pull Request that the comment relates to | `["e","pull_request_id"]` |
|
||||||
|
|
||||||
|
TODO: Research how other systems (radicle, gittea, github, etc) target specific lines for comments to ensure consistancy where possible.
|
||||||
|
|
||||||
|
### Issue
|
||||||
|
|
||||||
|
Issues are `kind 1` events with `content` beginning `NEW ISSUE\n`, followed by a description.
|
||||||
|
|
||||||
|
#### Tags
|
||||||
|
|
||||||
|
| Required | Description | Format |
|
||||||
|
| -------- | ------------------------------------------ | ---------- |
|
||||||
|
| X | Hashtag to identify as issue | `["t","code-issue"]` |
|
||||||
|
| X | title | `["title","insert title..."]` |
|
||||||
|
| X | repository | `["a", "30017:<pubkey>:<d-identifier>", "<relay url>"]` |
|
||||||
|
| | additional hashtags as required | `["t","bug"]` |
|
||||||
|
| | searchable references to commits | `["c","commit id (SHA-1 hash)"]` |
|
||||||
|
| | references to branches (`full-fidelity` model only) | `["e","branch_id"]` |
|
||||||
|
| | references to Pull Requests | `["e","pull_request_id"]` |
|
||||||
|
|
||||||
|
TODO: status updates
|
||||||
|
|
||||||
|
### Branch (Full Fidelity Model Only)
|
||||||
|
|
||||||
|
A `kind 317` event represents a branch. Unlike in git, the branch head changes when a Merge or Commit event is made referencing it whilst the original branch reference never changes.
|
||||||
|
|
||||||
|
`content` specifies the branch title.
|
||||||
|
|
||||||
|
#### Tags
|
||||||
|
| Required | Description | Format |
|
||||||
|
| -------- | ------------------------------------------ | ---------- |
|
||||||
|
| X | repository | `["a", "30017:<pubkey>:<d-identifier>", "<relay url>"]` |
|
||||||
|
|
||||||
|
### Merge (Full Fidelity Model Only)
|
||||||
|
|
||||||
|
The `kind 117` event merges one branch into another at the specified commit.
|
||||||
|
|
||||||
|
It can also be used to move the branch head onto a different commit. For example, replicating the force push of a branch which moves its head back to a previous commit.
|
||||||
|
|
||||||
|
`content` SHOULD equal `""`
|
||||||
|
|
||||||
|
| Required | Description | Format |
|
||||||
|
| -------- | ------------------------------------------ | ---------- |
|
||||||
|
| X | repository | `["a", "30017:<pubkey>:<d-identifier>", "<relay url>"]` |
|
||||||
|
| X | commit id to merge | `["c","commit id (SHA-1 hash)"]` |
|
||||||
|
| X | branch to be merged into | `["e","branch_id"]` |
|
||||||
|
| | branch to be merged from | `["from-branch","branch_id"]` |
|
||||||
|
| | Pull Request to close | `["e","pull_request_event_id"]` |
|
||||||
|
|
||||||
|
### Tag (Full Fidelity Model Only)
|
||||||
|
|
||||||
|
This `kind 417` event mirrors the git Tag feature.
|
||||||
|
|
||||||
|
`content` contains only the Tag label eg `v0.1.2`.
|
||||||
|
|
||||||
|
##### Tags
|
||||||
|
|
||||||
|
| Required | Description | Format |
|
||||||
|
| -------- | ------------------------------------------ | ---------- |
|
||||||
|
| X | repository | `["a", "30017:<pubkey>:<d-identifier>", "<relay url>"]` |
|
||||||
|
| X | commit id to tag | `["c","commit id (SHA-1 hash)"]` |
|
||||||
Loading…
Reference in New Issue
Block a user