nips/17.md

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.

2. 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.
   2. 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.
   3. web clients can offer a rich UX including the latest repository status without having to synchronize with a git server.
   4. 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

2. 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)"]