From bf611d0ee24afe47700c134908223a62daba6612 Mon Sep 17 00:00:00 2001 From: Biz Date: Mon, 31 Mar 2025 15:13:34 +1000 Subject: [PATCH 1/5] First naive implementation of permalinks --- 34.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/34.md b/34.md index 56ede853..93ecfa8f 100644 --- a/34.md +++ b/34.md @@ -165,6 +165,26 @@ 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. +## Permalinks + +Permalinks represent a link to one or more lines of a specific file in a repository. Client should render the content tag as preformatted text or can fetch and parse the original file's content for greater accuracy. + +```json +{ + "kind": 1623, + "content": "", + "tags": [ + ["a", "30617::"], + ["l", "markdown"], + ["extension", "md"], + ["repo", "https://github.com/nostr-protocol/nostr"], + ["branch", "permalink"], + ["refs//",""] + ["file", "34.md"], + ["lines", 170, 183] + ] +} +``` ## Possible things to be added later From 96c43d11682f49dd988a67b8e00b424e9959dfba Mon Sep 17 00:00:00 2001 From: Biz Date: Mon, 31 Mar 2025 20:58:58 +1000 Subject: [PATCH 2/5] more refining of permalink kind --- 34.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/34.md b/34.md index 93ecfa8f..2ce91445 100644 --- a/34.md +++ b/34.md @@ -169,15 +169,14 @@ The Status of a patch-revision defaults to either that of the root-patch, or `16 Permalinks represent a link to one or more lines of a specific file in a repository. Client should render the content tag as preformatted text or can fetch and parse the original file's content for greater accuracy. -```json +```jsonc { "kind": 1623, "content": "", "tags": [ ["a", "30617::"], ["l", "markdown"], - ["extension", "md"], - ["repo", "https://github.com/nostr-protocol/nostr"], + ["repo", "https://github.com/nostr-protocol/nostr.git"], ["branch", "permalink"], ["refs//",""] ["file", "34.md"], From bd699c6349e5a33ac8835a3ec415959d5c1e0956 Mon Sep 17 00:00:00 2001 From: Biz Date: Fri, 4 Apr 2025 18:12:26 +1000 Subject: [PATCH 3/5] added more detail on permalink kind --- 34.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/34.md b/34.md index 2ce91445..bc3278a5 100644 --- a/34.md +++ b/34.md @@ -167,24 +167,44 @@ The Status of a patch-revision defaults to either that of the root-patch, or `16 ## Permalinks -Permalinks represent a link to one or more lines of a specific file in a repository. Client should render the content tag as preformatted text or can fetch and parse the original file's content for greater accuracy. +Permalink events (`kind: 1623`) represent a permanent reference to specific lines within a file from a Git repository. They are intended to directly reference code or documentation precisely and immutably. Clients should render the event's `content` field as preformatted text (code blocks). ```jsonc { "kind": 1623, - "content": "", + "content": "", "tags": [ - ["a", "30617::"], - ["l", "markdown"], + // Reference to the repo's 30617 event if one exists + ["a", "30617::"], + // Explicit repository URL (optional if resolvable via 'a' tag, recommended for interoperability) ["repo", "https://github.com/nostr-protocol/nostr.git"], - ["branch", "permalink"], + // refs associated with the repository (mandatory) ["refs//",""] + + // Specific commit identifier referencing the repository state (mandatory) + ["commit", ""], + // Path to the specific file in the repository (mandatory) ["file", "34.md"], - ["lines", 170, 183] + + // Start and end lines referenced within the file (optional, otherwise the event refers to the complete file) + ["lines", "172", "196"], + // Language identifier for syntax highlighting (optional but recommended) + ["l", "markdown"], + // Optional description providing context or purpose of permalink + ["description", "Specification for permalink events within NIP-34"] ] } ``` +### Client Recommendations + +Clients rendering permalink events SHOULD: + +- Fetch and display the exact lines from the referenced commit and file if the content is not explicitly included or for verification. +- Display provided code/text using syntax highlighting according to the specified language tag (`l`). +- Offer navigation or direct links to view the file within external repository browsers or clients. + + ## Possible things to be added later - "branch merge" kind (specifying a URL from where to fetch the branch to be merged) From 44bda346e7bf8dc43f8d9d41f7747040c744e98a Mon Sep 17 00:00:00 2001 From: Biz Date: Thu, 10 Apr 2025 20:42:21 +1000 Subject: [PATCH 4/5] added initial diff kind --- 34.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 50 insertions(+), 9 deletions(-) diff --git a/34.md b/34.md index bc3278a5..94d530b0 100644 --- a/34.md +++ b/34.md @@ -165,6 +165,51 @@ 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 Diffs + +Git Diff events (`kind: 1622`) represent changes between two commits within a Git repository, encapsulated as a unified diff. This event type is distinct from Git patches as it explicitly represents the state difference between two specific commits rather than modifications intended for direct application. + +Clients should render the event's `content` field as preformatted unified diff text (commonly displayed with diff highlighting). + +### Event Format + +```jsonc +{ + "kind": 1622, + "content": "", + "tags": [ + // Addressing tag for repository identification + ["a", "30617::"], + // Explicit commit ID this diff represents (mandatory) + ["commit", ""], + // Parent commit ID from which the diff is generated (mandatory) + ["parent-commit", ""], + + // Optional specification of repository URL for interoperability + ["repo", "https://github.com/user/repo.git"], + // Optional branch or reference for context + ["branch", "feature/update-nip34"], + // File path within the repository affected by this diff (optional but recommended if diff is single-file) + ["file", "src/module/example.ts"], + // Optional start and end lines in the diff context (recommended for precise referencing) + ["lines", "172", "196"], + // Optional description for context or explanation of changes + ["description", "Implements new diff handling in NIP-34"] + ] +} +``` + +Clients rendering Git Diff events SHOULD: + +- Display the unified diff content with syntax highlighting for added/removed lines. +- Provide options to view or open the diff context within external repository browsers or local Git clients. +- Use commit and parent-commit identifiers for querying or fetching the exact commit state. +- Clearly indicate repository, branch, and file context if provided. + +This detailed structure improves clarity, usability, and interoperability, providing clients with comprehensive context and ensuring precise referencing and rendering. +The first patch in a series MAY be a cover letter in the format produced by `git format-patch`. + ## Permalinks Permalink events (`kind: 1623`) represent a permanent reference to specific lines within a file from a Git repository. They are intended to directly reference code or documentation precisely and immutably. Clients should render the event's `content` field as preformatted text (code blocks). @@ -177,27 +222,23 @@ Permalink events (`kind: 1623`) represent a permanent reference to specific line // Reference to the repo's 30617 event if one exists ["a", "30617::"], // Explicit repository URL (optional if resolvable via 'a' tag, recommended for interoperability) - ["repo", "https://github.com/nostr-protocol/nostr.git"], + ["repo", ""], // refs associated with the repository (mandatory) ["refs//",""] - // Specific commit identifier referencing the repository state (mandatory) ["commit", ""], // Path to the specific file in the repository (mandatory) - ["file", "34.md"], + ["file", ""], // Start and end lines referenced within the file (optional, otherwise the event refers to the complete file) - ["lines", "172", "196"], + ["lines", "", ""], // Language identifier for syntax highlighting (optional but recommended) - ["l", "markdown"], - // Optional description providing context or purpose of permalink - ["description", "Specification for permalink events within NIP-34"] + ["l", ""], + ["description", ""] ] } ``` -### Client Recommendations - Clients rendering permalink events SHOULD: - Fetch and display the exact lines from the referenced commit and file if the content is not explicitly included or for verification. From 396beff41b3421bb42ef480586f5644a46ff86f5 Mon Sep 17 00:00:00 2001 From: Biz Date: Fri, 11 Apr 2025 17:05:32 +1000 Subject: [PATCH 5/5] minor edits --- 34.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/34.md b/34.md index 94d530b0..ca3c6af3 100644 --- a/34.md +++ b/34.md @@ -165,33 +165,30 @@ 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 Diffs Git Diff events (`kind: 1622`) represent changes between two commits within a Git repository, encapsulated as a unified diff. This event type is distinct from Git patches as it explicitly represents the state difference between two specific commits rather than modifications intended for direct application. Clients should render the event's `content` field as preformatted unified diff text (commonly displayed with diff highlighting). -### Event Format - ```jsonc { "kind": 1622, "content": "", "tags": [ - // Addressing tag for repository identification + // Reference to the repo's 30617 event if one exists ["a", "30617::"], // Explicit commit ID this diff represents (mandatory) ["commit", ""], // Parent commit ID from which the diff is generated (mandatory) ["parent-commit", ""], - // Optional specification of repository URL for interoperability + // Explicit repository URL (optional if resolvable via 'a' tag, recommended for interoperability) ["repo", "https://github.com/user/repo.git"], - // Optional branch or reference for context - ["branch", "feature/update-nip34"], + // refs associated with the repository + ["refs//",""] // File path within the repository affected by this diff (optional but recommended if diff is single-file) - ["file", "src/module/example.ts"], + ["file", ""], // Optional start and end lines in the diff context (recommended for precise referencing) ["lines", "172", "196"], // Optional description for context or explanation of changes @@ -208,7 +205,6 @@ Clients rendering Git Diff events SHOULD: - Clearly indicate repository, branch, and file context if provided. This detailed structure improves clarity, usability, and interoperability, providing clients with comprehensive context and ensuring precise referencing and rendering. -The first patch in a series MAY be a cover letter in the format produced by `git format-patch`. ## Permalinks @@ -245,7 +241,6 @@ Clients rendering permalink events SHOULD: - Display provided code/text using syntax highlighting according to the specified language tag (`l`). - Offer navigation or direct links to view the file within external repository browsers or clients. - ## Possible things to be added later - "branch merge" kind (specifying a URL from where to fetch the branch to be merged)