docs: n34 book

Signed-off-by: Awiteb <a@4rs.nl>

docs/patch/README.md

@@ -0,0 +1,21 @@
+# Patch Management
+
+In `n34`, patch management is designed to give you complete control. You can
+manually generate patch files using `git-format-patch` and then broadcast them
+to Nostr relays. This ensures that you have full authority over the content
+and structure of your patches, allowing for precise customization as per your
+requirements.
+
+Similarly, when fetching patches, `n34` provides them to you without
+automatically applying, merging, or checking them. This empowers you to review
+the patches at your own pace and decide whether to merge or apply them as
+needed. You retain full control over the entire process, ensuring a tailored
+approach to patch management.
+
+## Patch Status Management
+
+You can assign a status to original patches, but revision patches do not have
+a specific status assigned to them. Instead, they inherit the status of the
+original patch. However, if the original patch is marked as `Applied/Merged`,
+the revision patch must be explicitly tagged to claim the same status. If not
+tagged, the revision patch status will be `Closed`.

docs/patch/apply.md

@@ -0,0 +1,30 @@
+# Apply an Open Patch
+
+> `n34 patch apply` command
+
+**Usage:**
+```
+Set an open patch status to applied
+
+Usage: n34 patch apply [OPTIONS] <PATCH_ID> [APPLIED_COMMITS]...
+
+Arguments:
+  <PATCH_ID>            The open patch id to apply it. Must be orignal root patch or revision root
+  [APPLIED_COMMITS]...  The applied commits
+
+Options:
+      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
+```
+
+Creates a kind `1631` event (Applied/Merged status) for the specified patch. The
+patch must be in open status.
+
+You can specify either an original patch or revision patch ID, but the status
+event will only reference the original patch. Revision patches will be mentioned
+in the event.
+
+The `APPLIED_COMMITS` field serves to inform clients about the status of
+specific commits, whether they have been applied or not. If you need to retrieve
+the list of commits from a specific point (such as the tip of the master branch)
+up to the `HEAD`, you can use the following Git command: `git log --pretty=%H
+'origin/master..HEAD'`.

docs/patch/close.md

@@ -0,0 +1,20 @@
+# Closes an Open or Drafted Patch
+
+> `n34 patch close` command
+
+**Usage:**
+```
+Closes an open or drafted patch
+
+Usage: n34 patch close [OPTIONS] <PATCH_ID>
+
+Arguments:
+  <PATCH_ID>  The open/drafted patch id to close it. Must be orignal root patch
+
+Options:
+      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
+```
+
+Issue a kind `1632` (Close status) for the specified patch. The patch have to
+be open or drafted.
+

docs/patch/draft.md

@@ -0,0 +1,19 @@
+# Draft an Open Patch
+
+> `n34 patch draft` command
+
+**Usage:**
+```
+Converts an open patch to draft state
+
+Usage: n34 patch draft [OPTIONS] <PATCH_ID>
+
+Arguments:
+  <PATCH_ID>  The open patch id to draft it. Must be orignal root patch
+
+Options:
+      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
+```
+
+Issue a kind `1633` (Draft status) for the specified patch. The patch have to
+be open.

docs/patch/fetch.md

@@ -0,0 +1,21 @@
+# Fetch a Patch By ID
+
+> `n34 patch fetch` command
+
+**Usage:**
+```
+Fetches a patch by its id
+
+Usage: n34 patch fetch [OPTIONS] <PATCH_ID>
+
+Arguments:
+  <PATCH_ID>  The patch id to fetch it
+
+Options:
+      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
+  -o, --output <PATH>              Output directory for the patches. Default to the current directory
+```
+
+Fetches patches using their original patch ID. All fetched patches will be saved
+to the specified output directory (current directory by default). You can then
+apply or merge these patches into your branch as needed.

docs/patch/list.md

@@ -0,0 +1,20 @@
+# List Repositories Patches
+
+> `n34 patch list` command
+
+**Usage:**
+```
+List the repositories patches
+
+Usage: n34 patch list [OPTIONS] [NADDR-NIP05-OR-SET]...
+
+Arguments:
+  [NADDR-NIP05-OR-SET]...  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
+
+Options:
+      --limit <LIMIT>  Maximum number of patches to list [default: 15]
+```
+
+List the repositories patches. By default `n34` will look for `nostr-address`
+file and extract the repositories from it.
+

docs/patch/merge.md

@@ -0,0 +1,28 @@
+# Merge an Open Patch
+
+> `n34 patch merge` command
+
+**Usage:**
+```
+Set an open patch status to merged
+
+Usage: n34 patch merge [OPTIONS] <PATCH_ID> <MERGE_COMMIT>
+
+Arguments:
+  <PATCH_ID>      The open patch id to merge it. Must be orignal root patch or revision root
+  <MERGE_COMMIT>  The merge commit id
+
+Options:
+      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
+```
+
+Creates a kind `1631` event (Applied/Merged status) for the specified patch. The
+patch must be in open status.
+
+You can specify either an original patch or revision patch ID, but the status
+event will only reference the original patch. Revision patches will be mentioned
+in the event.
+
+You can get the `MERGE_COMMIT` commit using `git rev-parse HEAD` command if
+the merge commit in the `HEAD` or use `HEAD~n` where the `n` is the number of
+commits the merge commit before the HEAD

docs/patch/reopen.md

@@ -0,0 +1,20 @@
+# Reopens a Closed or Drafted Patch
+
+> `n34 patch reopen` command
+
+**Usage:**
+```
+Reopens a closed or drafted patch
+
+Usage: n34 patch reopen [OPTIONS] <PATCH_ID>
+
+Arguments:
+  <PATCH_ID>  The closed/drafted patch id to reopen it. Must be orignal root patch
+
+Options:
+      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
+```
+
+Issue a kind `1632` (Close status) for the specified patch. The patch have to
+be closed or drafted.
+

docs/patch/send.md

@@ -0,0 +1,22 @@
+# Send Patches to a Repository
+
+> `n34 patch send` command
+
+**Usage:**
+```
+Send one or more patches to a repository
+
+Usage: n34 patch send [OPTIONS] <PATCH-PATH>...
+
+Arguments:
+  <PATCH-PATH>...  List of patch files to send (space separated)
+
+Options:
+      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
+      --original-patch <EVENT-ID>  Original patch ID if this is a revision of it
+```
+
+Send your generated patches to the repositories specified using the `--repo`
+option or retrieved from the `nostr-address` file. When submitting a revision
+of an existing patch, include the original patch ID to ensure it’s correctly
+referenced in your revision patch event.