diff --git a/9A.md b/9A.md new file mode 100644 index 00000000..79a6fffe --- /dev/null +++ b/9A.md @@ -0,0 +1,81 @@ +NIP-9A +====== + +Comment-based Patching +---------------------- + +`draft` `optional` + +A patch is a `kind:1111` [NIP-22](22.md) comment that references the patched event as its parent and whose `.content` is a `PATCH` label followed by a patch in a human-readable patch syntax. + +Clients that support this can apply the patch on top of the original event and hide the patch comment. + +Every other client can just display the patch as a normal `kind:1111` comment which is relatively human-readable and clearly labeled as a patch. + +```json +{ + "kind": 1111, + "content": "PATCH\n", + "tags": [ + ["e", "", "", ""], + ["k", ""], + ] +} +``` + +## Patch syntax + +`` is formed by one or more lines. + +Lines starting with a number modify the `.content` of the patched event: + +``` + - + +``` + +Lines starting with a `t` modify a human-facing tag (e.g. `title`, `description`, `subject`, `picture`) of the patched event, replacing it with the given value: + +``` +t +``` + +The indexes and amounts refer to unicode characters, not bytes. + +## Broken patches + +In case a patch can't be applied, the reader client can just leave it as it is, displayed as a normal comment. + +## Multiple patches + +If more than one patch has to be made, they should all target the same original event (i.e. the second patch shouldn't tag the first patch), and the reader client should apply one after the other, in temporal sequence. + +## Recommendations + +This method should not be used to completely replace a thing (better delete and make a new one) or to continuously update it over time (better use replaceable events). + +It is meant for fixing typos, adding missing content and other small text issues. + +Therefore, clients should prevent users from: + - generating too large patches; + - publishing too many of such patches; + - making patches many days after the original event was published. + +Likewise, clients reading these patches should refrain to apply them (and leave them only as hanging comments) if they are + - too large; + - too many; + - published too long after the original event was published. + +Also, when generating content patches clients should prefer to do it over full words instead of over characters, in benefit of human-readability, unless perhaps when what is being fixed is a single character inside a word. + +## Target kinds + +The event kinds that are expected to be patchable this way are: + - `1` (short text notes), + - `11` (forum threads), + - `1111` (comments), + - `24` (public messages), + - `1621` (issues). + +## Unspecified possibilities + +- I don't know if this is a good idea, but it may be a cool dynamic to allow people to publish patches to events authored by someone else, but in this case these should never be applied automatically, only upon user action that clearly implies this patch isn't by the original author (e.g. by clicking on the patch event that would otherwise just stay there as a normal weird-looking comment).