Compare commits

..

9 Commits

Author SHA1 Message Date
Leo Wandersleb
9b7883e98b Require tags to have at least one string
fixes #1193
2024-04-24 12:18:27 -04:00
Alex Gleason
cab47cf0f1 Merge pull request #1187 from AsaiToshiya/AsaiToshiya-patch-7
README: add status kinds of NIP-34
2024-04-21 22:37:50 -05:00
Asai Toshiya
eb3a857288 README: add status kinds of NIP-34 2024-04-22 12:35:48 +09:00
DanConwayDev
403b5199a4 NIP-34: add status events
merge-commit and applied-commit-id tags enable discussion of patches to be
mapped to lines of code accepted into the master branch
2024-04-17 17:46:34 -03:00
DanConwayDev
0b62729e31 NIP-34: clarify cover letters
remove cover letters from 'possible things to be added later' and
add a clarification that can they can be added through patches
2024-04-17 17:46:34 -03:00
DanConwayDev
8225a018c7 NIP-34: optional tags to improve discoverability
earliest-unique-commit r tag enables clients to:
 - retrieve all repo events refering to a local git repo
 - group repo events with different identifers that refer to same repo
 - retrieve all patches for a local repo,
   irespective of the tagged repo event

current-commit-id r tag enables clients to prevent accidental submission of a patch,
which has already been proposed

root-revision tag enables clients to filter out proposal revisions
from a list of proposals
2024-04-17 17:46:34 -03:00
DanConwayDev
cb0d35a5f9 NIP-34: optional additional repo maintainers
can be used by clients to tag multiple maintainers in patches

helps clients identify whether multiple repo events for the same repository
are complementary or in competion
2024-04-17 17:46:34 -03:00
DanConwayDev
46ea8dcf9c NIP-34: add repo-id standard
suggested guidance for repo-id
2024-04-17 17:46:34 -03:00
DanConwayDev
d607a288b5 NIP-34: clarify nip10 thread application
for consistancy and so that the intended order of patches is easier to ascertain

enables additional patches to be appended to a patch set, supporting a PR-like workflow alongside
patch-over-email-like workflow
2024-04-17 17:46:34 -03:00
4 changed files with 57 additions and 59 deletions

2
01.md
View File

@@ -56,7 +56,7 @@ To prevent implementation differences from creating a different event ID for the
### Tags
Each tag is an array of strings of arbitrary size, with some conventions around them. Take a look at the example below:
Each tag is an array of one or more strings, with some conventions around them. Take a look at the example below:
```jsonc
{

61
34.md
View File

@@ -17,17 +17,20 @@ Git repositories are hosted in Git-enabled servers, but their existence can be a
"kind": 30617,
"content": "",
"tags": [
["d", "<repo-id>"],
["d", "<repo-id>"], // usually kebab-case short name
["name", "<human-readable project name>"],
["description", "brief human-readable project description>"],
["web", "<url for browsing>", ...], // a webpage url, if the git server being used provides such a thing
["clone", "<url for git-cloning>", ...], // a url to be given to `git clone` so anyone can clone it
["relays", "<relay-url>", ...] // relays that this repository will monitor for patches and issues
["earliest-unique-commit", "<commit-id>"] // usually root commit but a recent commit for forks
["r", "<earliest-unique-commit-id>"] // so clients can subscribe to all events related to a local git repo
["maintainers", "<other-recognized-maintainer>", ...]
]
}
```
The tags `web`, `clone`, `relays` can have multiple values.
The tags `web`, `clone`, `relays`, `maintainers` can have multiple values.
Except `d`, all tags are optional.
@@ -35,23 +38,30 @@ Except `d`, all tags are optional.
Patches can be sent by anyone to any repository. Patches to a specific repository SHOULD be sent to the relays specified in that repository's announcement event's `"relays"` tag. Patch events SHOULD include an `a` tag pointing to that repository's announcement address.
Patches in a patch set SHOULD include a NIP-10 `e` `reply` tag pointing to the previous patch.
The first patch revision in a patch revision SHOULD include a NIP-10 `e` `reply` to the original root patch.
```jsonc
{
"kind": 1617,
"content": "<patch>", // contents of <git format-patch>
"tags": [
["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
["r", "<earliest-unique-commit-id-of-repo>"] // so clients can subscribe to all patches sent to a local git repo
["p", "<repository-owner>"],
["p", "<other-user>"], // optionally send the patch to another user to bring it to their attention
// for the first patch in a thread or series
["t", "root"],
["t", "root"], // ommited for additional patches in a series
// for the first patch in a revision
["t", "root-revision"],
// optional tags for when it is desirable that the merged patch has a stable commit id
// these fields are necessary for ensuring that the commit resulting from applying a patch
// has the same id as it had in the proposer's machine -- all these tags can be omitted
// if the maintainer doesn't care about these things
["commit", "<current-commit-id>"],
["r", "<current-commit-id>"] // so clients can find existing patches for a specific commit
["parent-commit", "<parent-commit-id>"],
["commit-pgp-sig", "-----BEGIN PGP SIGNATURE-----..."], // empty string for unsigned commit
["committer", "<name>", "<email>", "<timestamp>", "<timezone offset in minutes>"],
@@ -59,6 +69,8 @@ Patches can be sent by anyone to any repository. Patches to a specific repositor
}
```
The first patch in a series MAY be a cover letter in the format produced by `git format-patch`.
## 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.
@@ -94,9 +106,46 @@ Replies are also Markdown text. The difference is that they MUST be issued as re
}
```
## Status
Root Patches and Issues have a Status that defaults to 'Open' and can be set by issuing Status events.
```jsonc
{
"kind": 1630, // Open
"kind": 1631, // Applied / Merged for Patches; Resolved for Issues
"kind": 1632, // Closed
"kind": 1633, // Draft
"content": "<markdown text>",
"tags": [
["e", "<issue-or-original-root-patch-id-hex>", "", "root"],
["e", "<accepted-revision-root-id-hex>", "", "reply"], // for when revisions applied
["p", "<repository-owner>"],
["p", "<root-event-author>"],
["p", "<revision-author>"],
// optional for improved subscription filter efficency
["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"],
["r", "<earliest-unique-commit-id-of-repo>"]
// optional for `1631` status
["e", "<applied-or-merged-patch-event-id>", "", "mention"], // for each
// when merged
["merge-commit", "<merge-commit-id>"]
["r", "<merge-commit-id>"]
// when applied
["applied-as-commits", "<commit-id-in-master-branch>", ...]
["r", "<applied-commit-id>"] // for each
]
}
```
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.
## Possible things to be added later
- "status" kind (for letting people know a patch was merged or an issue was fixed or won't be fixed)
- "branch merge" kind (specifying a URL from where to fetch the branch to be merged)
- "cover letter" kind (to which multiple patches can refer and serve as a unifying layer to them)
- inline file comments kind (we probably need one for patches and a different one for merged files)

52
91.md
View File

@@ -1,52 +0,0 @@
NIP-91
======
EOSE Extensions
---------------
`draft` `optional`
This NIP defines an extension to the EOSE message that allows relays to convey additional information to clients.
## Extended EOSE
An extended EOSE is an EOSE message, with the 2nd parameter being the "extensions object". For example: `["EOSE","example-sub",{"example_ext":"example value"}]`
An EOSE extension is a field in the extensions object. This may contain any value.
Clients MUST NOT rely on relays implementing any extensions.
## Extensions
This NIP defines a set of standard extensions.
### `next_created_at`
`recommended`
The value of this extension MUST be an integer if present, and should specify the next `until` value the client should use for pagination.
This MAY be higher or lower than the lowest `created_at`, and the clients SHOULD NOT perform any modifications to this value.
### `cursor`
The value of this extension MUST be a string or `null` if present, and represents a cursor the client can use to paginate this query.
If the value is `null`, then it indicates that no more events are available for the given set of filters.
To get more events, the client MUST send a `REQ` with the same filters (except limit, which can be changed), and the `cursor` string
in the 1st filter with the key `cursor`. Example:
```jsonc
< ["REQ", "examplereq1", {"kinds": [1], "limit": 1}, {"authors": ["..."], "limit": 1}]
> ["EVENT", "examplereq1", ...]
> ["EOSE", "examplereq1", {"cursor": "example-cursor-string", ...}]
< ["CLOSE", "examplereq1"]
< ["REQ", "examplereq2", {"kinds": [1], "limit": 5, "cursor": "example-cursor-string"}, {"authors": ["..."], "limit": 5}]
> ["EVENT", "examplereq2", ...]
...
```
This cursor MUST be valid for the duration of the connection, and MAY be valid in a new connection. A relay may indicate a cursor is no longer valid
by sending a CLOSED with the prefix `bad-cursor: `.
### `auth_recommended`
The value of this extension MUST be a boolean if present, and indicates if the client should `AUTH` to get more events that match this query.
This is a less disruptive alternative to `CLOSED` with `auth-required:` for filters that don't explicitly ask for access controlled events,
but may match them.

View File

@@ -114,6 +114,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
| `1617` | Patches | [34](34.md) |
| `1621` | Issues | [34](34.md) |
| `1622` | Replies | [34](34.md) |
| `1630`-`1633` | Status | [34](34.md) |
| `1971` | Problem Tracker | [nostrocket][nostrocket] |
| `1984` | Reporting | [56](56.md) |
| `1985` | Label | [32](32.md) |