reya/n34
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: n34 book

Browse Source 
Signed-off-by: Awiteb <a@4rs.nl>
This commit is contained in:
Awiteb
2025-08-01 18:46:02 +00:00
parent 2630104e99
commit bd3ba1bdbf
37 changed files with 1203 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -1 +1,2 @@
/target /target
/book

10
book.toml Normal file
View File

@@ -0,0 +1,10 @@
[book]
authors = ["Awiteb"]
language = "en"
multilingual = false
src = "docs"
title = "n34 documentation"
[output.html]
git-repository-icon = "fa-git"
git-repository-url = "https://git.4rs.nl/awiteb/n34.git"

33
docs/SUMMARY.md Normal file
View File

@@ -0,0 +1,33 @@
# n34 documentation
- [Command Line Usage](commands.md)
- [Managing Repository and Relay Sets](sets/README.md)
- [Create a Set](sets/new.md)
- [Modify a Set](sets/update.md)
- [Show Sets](sets/show.md)
- [Remove a Set](sets/remove.md)
- [Manage Configuration](config/README.md)
- [Default PoW Difficulty](config/pow.md)
- [Fallback Relays](config/relays.md)
- [NIP-46 Bunker](config/bunker.md)
- [Secret Key Keyring](config/keyring.md)
- [Manage Repositories](repo/README.md)
- [Broadcast and Update a Git Repository](repo/announce.md)
- [View Git Repository Details](repo/view.md)
- [Issue Management](issue/README.md)
- [Create an Issue](issue/new.md)
- [View an Issue By ID](issue/view.md)
- [Reopen a Closed Issue](issue/reopen.md)
- [Closes an Open Issue](issue/close.md)
- [Resolves an Issue](issue/resolve.md)
- [List Repositories Issues](issue/list.md)
- [Patch Management](patch/README.md)
- [Send Patches to a Repository](patch/send.md)
- [Fetch a Patch By ID](patch/fetch.md)
- [Reopens a Closed or Drafted Patch](patch/reopen.md)
- [Closes an Open or Drafted Patch](patch/close.md)
- [Draft an Open Patch](patch/draft.md)
- [Apply an Open Patch](patch/apply.md)
- [Merge an Open Patch](patch/merge.md)
- [List Repositories Patches](patch/list.md)
- [Reply to Issues and Patches](reply.md)

63
docs/commands.md Normal file
View File

@@ -0,0 +1,63 @@
# Command-Line Usage
## Options
The `n34` command-line tool accepts the following options:
- `-s`, `--secret-key`: Your Nostr secret key (in `nsec` format), used for
signing events.
- `-b`, `--bunker-url`: The URL of a NIP-46 bunker service used for remote
signing of events.
- `-r`, `--relays`: A relay to read from and write to. This option can be
specified multiple times to connect to several relays.
- `--pow`: Sets the Proof of Work difficulty required when creating events.
- `--config`: Specifies a custom path to the configuration file (Default:
`$HOME/.config/n34/config.toml`).
- `-v`, `--verbose...`: Increases the logging verbosity. Can be used multiple
times for more detail (e.g., `-v`, `-vv`).
**Note:** The `--secret-key` and `--bunker-url` options are mutually exclusive.
You must provide exactly one signing method.
## Multiple Repositories
Commands that interact with a repository, such as submitting an issue or a
patch, can accept multiple repository addresses (`naddr`). This feature is
useful for projects with multiple maintainers who each have their own repository
fork.
> **Important:** When you provide multiple repositories, `n34` does not
create a separate issue or patch for each one. Instead, it creates a single
event that references all of the specified repositories.
## The `nostr-address` File
The `nostr-address` file is a plain text file that stores a list of project
repository addresses. This allows the `n34` to find and use them
without requiring you to enter the addresses manually.
### Format
- Each line must contain a single addressable event coordinate `naddr` which is
the repository address.
- Lines beginning with a `#` are treated as comments and are ignored.
- Empty lines are also ignored.
## Passing repositories
By default, `n34` will look for a `nostr-address` file to extract repositories
from it. This is why repositories are not required for commands like `patch
send` and `issue new`. You can also pass repositories using the `--repo`
option or the `<NADDR-NIP05-OR-SET>` argument for commands that accept them. The
supported formats for manual input are:
- A [NIP-19] addressable event coordinate `naddr`.
- A [NIP-05] identifier and repository name, in the format
`<nip05>/<repo-name>`.
- A set name that contains repository addresses.
You do not need to specify relays for these commands if your `naddr` or `NIP-05`
identifier already includes relays; `n34` will automatically extract them.
[NIP-19]: https://github.com/nostr-protocol/nips/blob/master/19.md
[NIP-05]: https://github.com/nostr-protocol/nips/blob/master/05.md

7
docs/config/README.md Normal file
View File

@@ -0,0 +1,7 @@
# Manage Configuration
Configuration allows you to set default values for various command parameters,
such as fallback relays, Proof of Work (PoW) difficulty, a default bunker URL,
and your Nostr private key (keyring). This avoids the need to enter your private key,
bunker URL, relays, or PoW difficulty for every command, making `n34` more
convenient to use.

27
docs/config/bunker.md Normal file
View File

@@ -0,0 +1,27 @@
# NIP-46 Bunker
> `n34 config bunker` command
**Usage:**
```
Sets a URL of NIP-46 bunker server used for signing events
Usage: n34 config bunker [BUNKER_URL]
Arguments:
[BUNKER_URL] Nostr Connect URL for the bunker. Omit this to remove the current bunker URL
```
This command configures `n34` to use a remote signer ([NIP-46]), known as a
bunker, for all cryptographic operations.
When `n34` communicates with the bunker, it uses a persistent, locally-generated
keypair. You should add this keypair's public key to your bunker's list of
authorized applications. This allows `n34` to operate securely without needing
direct access to your main private key.
Once configured, actions such as fetching your public key or signing events are
delegated to the bunker. To remove the bunker configuration, run the command
again without providing a URL.
[NIP-46]: https://github.com/nostr-protocol/nips/blob/master/46.md

27
docs/config/keyring.md Normal file
View File

@@ -0,0 +1,27 @@
# Secret Key Keyring
> `n34 config keyring` command
**Usage:**
```
Manages the secret key keyring, including enabling, disabling, or resetting it.
Usage: n34 config keyring <--enable|--disable|--reset>
Options:
--enable Enables the secret key keyring. You will be prompted for your key one last time to store it.
--disable Disables the secret key keyring. This removes the stored key and prevents new ones from being saved.
--reset Resets the keyring. This deletes the current key, allowing a new one to be stored on the next use.
```
To avoid entering your private key for every command, you can enable the keyring
to store it securely. First, run `n34 config keyring --enable`. The next time
you run an `n34` command that requires your private key, it will be saved
to your system's keyring. You will not need to enter it again for subsequent
commands.
To replace the stored key with a new one, use the `--reset` flag. To stop using
the keyring and remove the stored key, use the `--disable` flag.
`n34` uses your operating system's native secret management system. For example,
it uses `keyutils` on Linux and `Keychain` on macOS.

20
docs/config/pow.md Normal file
View File

@@ -0,0 +1,20 @@
# Default PoW Difficulty
> `n34 config pow`
**Usage:**
```
Sets the default PoW difficulty (0 if not specified)
Usage: n34 config pow <DIFFICULTY>
Arguments:
<DIFFICULTY> The new default PoW difficulty
```
This command configures the default Proof of Work (PoW) difficulty for newly
created events. This setting is applied to most generated events, but it
intentionally skips patch events. Because patches can be numerous, calculating
PoW for each one would significantly slow down operations.
If you want to disable the PoW just make it 0.

21
docs/config/relays.md Normal file
View File

@@ -0,0 +1,21 @@
# Fallback Relays
> `n34 config relays` command
**Usage:**
```
Sets the default fallback relays if none provided. Use this relays for read and write
Usage: n34 config relays [OPTIONS] [RELAYS]...
Arguments:
[RELAYS]... List of relay URLs to append to fallback relays. If empty, removes all fallback relays
Options:
--override Replace existing fallback relays instead of appending new ones
```
This command configures the default fallback relays, which `n34` uses to read
from and write to. To add relays, provide their URLs as arguments to append
them to the current list. Use the `--override` flag to replace the existing list
entirely. To clear all fallback relays, run the command without any arguments.

449
docs/index.html Normal file
View File

@@ -0,0 +1,449 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta property="og:title" content="n34 - CLI for NIP-34 and Nostr Code Collaboration">
<meta property="og:description" content="An open source CLI for sending and receiving Git issues, patches and comments over the Nostr protocol.">
<meta property="og:url" content="https://n34.dev">
<meta property="og:type" content="website">
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="n34 - CLI for NIP-34 and Nostr Code Collaboration">
<meta name="twitter:description" content="An open source CLI for sending and receiving Git issues, patches and comments over the Nostr protocol.">
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>n34 - CLI for NIP-34 and Nostr Code Collaboration</title>
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
background: radial-gradient(125% 125% at 50% 90%, #000000 40%, #072607 100%);
color: #ffffff;
line-height: 1.6;
min-height: 100vh;
}
.container {
max-width: 800px;
margin: 0 auto;
padding: 60px 20px;
}
.hero {
text-align: center;
margin-bottom: 80px;
}
.hero h1 {
font-size: 4rem;
font-weight: 300;
margin-bottom: 20px;
letter-spacing: 2px;
background: linear-gradient(135deg, #ffffff, #cccccc);
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
background-clip: text;
}
.hero p {
font-size: 1.2rem;
color: #cccccc;
margin-bottom: 40px;
max-width: 600px;
margin-left: auto;
margin-right: auto;
}
.buttons {
display: flex;
gap: 20px;
justify-content: center;
flex-wrap: wrap;
}
.btn {
display: inline-block;
padding: 14px 28px;
background: transparent;
border: 2px solid #ffffff;
color: #ffffff;
text-decoration: none;
border-radius: 8px;
font-weight: 500;
font-size: 1rem;
transition: all 0.3s ease;
min-width: 120px;
text-align: center;
}
.btn:hover {
background: #ffffff;
color: #0a0a0a;
transform: translateY(-2px);
box-shadow: 0 8px 25px rgba(255, 255, 255, 0.2);
}
.section {
margin-bottom: 60px;
}
.section h2 {
font-size: 2.2rem;
margin-bottom: 30px;
color: #ffffff;
font-weight: 400;
}
.section p {
font-size: 1.1rem;
color: #e0e0e0;
margin-bottom: 20px;
text-align: justify;
}
a {
color: #cccccc;
text-decoration: underline;
font-size: 1rem;
transition: color 0.3s ease;
}
a:hover {
color: #ffffff;
}
.features {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 30px;
margin-bottom: 60px;
}
.feature {
background: #1a1a1a;
padding: 30px;
border-radius: 12px;
border: 1px solid #333;
transition: transform 0.3s ease, border-color 0.3s ease;
}
.feature:hover {
transform: translateY(-5px);
border-color: #555;
}
.feature h3 {
font-size: 1.3rem;
margin-bottom: 15px;
color: #ffffff;
display: flex;
align-items: center;
gap: 10px;
}
.feature-icon {
font-size: 1.5rem;
}
.feature p {
color: #cccccc;
font-size: 1rem;
text-align: left;
}
.feature-list {
background: #111;
padding: 40px;
border-radius: 12px;
border: 1px solid #333;
margin-bottom: 60px;
}
.feature-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 20px;
margin-top: 20px;
}
.feature-column ul {
list-style: none;
padding: 0;
}
.feature-column li {
display: flex;
align-items: center;
margin-bottom: 12px;
font-size: 1rem;
padding: 8px 0;
}
.feature-check {
display: inline-block;
width: 20px;
height: 20px;
margin-right: 12px;
border-radius: 3px;
text-align: center;
line-height: 20px;
font-size: 12px;
font-weight: bold;
flex-shrink: 0;
}
.feature-check.completed {
background: #22c55e;
color: #ffffff;
}
.feature-check.pending {
background: #374151;
color: #9ca3af;
border: 1px solid #4b5563;
}
.feature-check.completed::after {
content: "✓";
}
.feature-check.pending::after {
content: "○";
}
.feature-text {
color: #e0e0e0;
}
.feature-text.pending {
color: #9ca3af;
}
.install-section {
background: #111;
padding: 40px;
border-radius: 12px;
border: 1px solid #333;
margin-bottom: 60px;
}
.install-section h2 {
margin-bottom: 20px;
text-align: center;
}
.code-block {
background: #000;
padding: 20px;
border-radius: 8px;
font-family: "Courier New", monospace;
font-size: 1rem;
color: #00ff00;
border: 1px solid #333;
overflow-x: auto;
margin: 15px 0;
}
.code-block p {
color: #777;
}
.code-block::before {
content: "$ ";
color: #888;
}
.links {
margin-top: 30px;
}
.links h3 {
font-size: 1.3rem;
margin-bottom: 15px;
color: #ffffff;
}
.links ul {
list-style: none;
}
.links li {
margin-bottom: 8px;
}
.links a {
color: #cccccc;
text-decoration: none;
font-size: 1rem;
transition: color 0.3s ease;
}
.links a:hover {
color: #ffffff;
}
.links a:before {
content: "→ ";
margin-right: 8px;
}
.status-badge {
display: inline-block;
padding: 4px 12px;
background: #1a4d1a;
color: #4ade80;
border-radius: 16px;
font-size: 0.8rem;
font-weight: 500;
margin-bottom: 20px;
}
.footer {
text-align: center;
padding: 40px 0;
border-top: 1px solid #333;
margin-top: 80px;
color: #888;
}
@media (max-width: 768px) {
.hero h1 {
font-size: 2.5rem;
}
.hero p {
font-size: 1.1rem;
}
.buttons {
flex-direction: column;
align-items: center;
}
.btn {
width: 200px;
}
.section h2 {
font-size: 1.8rem;
}
.features {
grid-template-columns: 1fr;
}
.feature-grid {
grid-template-columns: 1fr;
}
.install-section,
.feature-list {
padding: 20px;
}
}
</style>
</head>
<body>
<div class="container">
<div class="hero">
<div class="status-badge">✨ Looking for feedback</div>
<h1>n34</h1>
<p>
n34 is an open source command-line interface (CLI) tool for
sending and receiving Git issues, patches and comments over the
Nostr protocol. It supports creating, replying to, and managing
issues and patches, making Git collaboration decentralized and
censorship-resistant.
</p>
<div class="buttons">
<a href="https://n34.dev/commands.html" class="btn">Documentation</a>
<a href="https://git.4rs.nl/awiteb/n34.git" class="btn">Git Repository</a>
</div>
</div>
<div class="section">
<h2>Key Features</h2>
<div class="features">
<div class="feature">
<h3><span class="feature-icon">🔄</span>Complete Git Workflow</h3>
<p>Handle the full development lifecycle with patches, issues, replies, and status tracking, all through the decentralized Nostr protocol.</p>
</div>
<div class="feature">
<h3><span class="feature-icon">🔗</span><a href="https://github.com/nostr-protocol/nips/blob/master/34.md" target="_blank" rel="noreferrer">NIP-34</a> Compliant</h3>
<p>Fully implements the <a href="https://github.com/nostr-protocol/nips/blob/master/34.md" target="_blank" rel="noreferrer">NIP-34</a> specification for Git repositories on Nostr, ensuring compatibility with the decentralized ecosystem.</p>
</div>
<div class="feature">
<h3><span class="feature-icon">🛠️</span>Developer Friendly</h3>
<p>Intuitive CLI interface designed for developers who want to integrate Git workflows with Nostr seamlessly.</p>
</div>
<div class="feature">
<h3><span class="feature-icon">🔐</span>Self-Sovereign</h3>
<p>No accounts, no passwords, no centralized servers. You control your identity and data through cryptographic keys.</p>
</div>
</div>
</div>
<div class="feature-list">
<h2>Feature Roadmap</h2>
<p style="text-align: center; margin-bottom: 30px; color: #cccccc;">Current implementation status and upcoming features</p>
<div class="feature-grid">
<div class="feature-column">
<ul>
<li>
<span class="feature-check completed"></span>
<span class="feature-text">Repository announcements</span>
</li>
<li>
<span class="feature-check pending"></span>
<span class="feature-text pending">Repository state announcements</span>
</li>
<li>
<span class="feature-check completed"></span>
<span class="feature-text">Patches (Send, fetch and list)</span>
</li>
<li>
<span class="feature-check completed"></span>
<span class="feature-text">Issues (Send, view and list)</span>
</li>
<li>
<span class="feature-check completed"></span>
<span class="feature-text">Replies</span>
</li>
<li>
<span class="feature-check completed"></span>
<span class="feature-text">Issues and patches status</span>
</li>
<li>
<span class="feature-check pending"></span>
<span class="feature-text pending">Pull requests (<a href="https://github.com/nostr-protocol/nips/pull/1966" target="_blank" rel="noreferrer">nostr-protocol/nips#1966</a>)</span>
</li>
</ul>
</div>
<div class="feature-column">
<ul>
<li>
<span class="feature-check completed"></span>
<span class="feature-text">Gossip Model (<a href="https://github.com/nostr-protocol/nips/blob/master/65.md" target="_blank" rel="noreferrer">NIP-65</a>)</span>
</li>
<li>
<span class="feature-check completed"></span>
<span class="feature-text">Proof of Work (<a href="https://github.com/nostr-protocol/nips/blob/master/13.md" target="_blank" rel="noreferrer">NIP-13</a>)</span>
</li>
<li>
<span class="feature-check completed"></span>
<span class="feature-text">nostr: URI scheme (<a href="https://github.com/nostr-protocol/nips/blob/master/21.md" target="_blank" rel="noreferrer">NIP-21</a>)</span>
</li>
<li>
<span class="feature-check completed"></span>
<span class="feature-text">Signing using bunker (<a href="https://github.com/nostr-protocol/nips/blob/master/46.md" target="_blank" rel="noreferrer">NIP-46</a>)</span>
</li>
<li>
<span class="feature-check pending"></span>
<span class="feature-text pending">Signing using <a href="https://github.com/nostr-protocol/nips/blob/master/07.md" target="_blank" rel="noreferrer">NIP-07</a> proxy (<a href="https://crates.io/crates/nostr-browser-signer-proxy" target="_blank" rel="noreferrer">nostr-browser-signer-proxy</a>)</span>
</li>
<li>
<span class="feature-check completed"></span>
<span class="feature-text">Secret key keyring</span>
</li>
<li>
<span class="feature-check pending"></span>
<span class="feature-text pending">Code Snippets (<a href="https://github.com/nostr-protocol/nips/blob/master/C0.md" target="_blank" rel="noreferrer">NIP-C0</a>)</span>
</li>
<li>
<span class="feature-check completed"></span>
<span class="feature-text">In device relays and repos bookmark</span>
</li>
</ul>
</div>
</div>
</div>
<div class="install-section">
<h2>Quick Start</h2>
<p style="text-align: center; margin-bottom: 20px; color: #cccccc;">Get started with n34 in seconds</p>
<div class="code-block">cargo install n34</div>
<p style="text-align: center; margin: 20px 0; color: #888;">or</p>
<div class="code-block">
git clone https://git.4rs.nl/awiteb/n34.git && cd n34 && cargo build --release
<br>
<p># The execautable will be in target/release/n34<p>
</div>
<p style="text-align: center; margin-top: 20px; color: #cccccc;">Once installed, run <code style="background: #333; padding: 2px 6px; border-radius: 4px;">n34 --help</code> to see available commands.</p>
</div>
<div class="section">
<h2>Why Nostr?</h2>
<p>
Nostr is fundamentally different from traditional platforms because it's not an application or service, it's a decentralized protocol. This means any tool or app can integrate with it, enabling open, permissionless collaboration
without relying on centralized gatekeepers. Unlike proprietary systems, Nostr doesn't require emails, passwords, or accounts. You interact directly through relays, whether you self-host your own or use public ones, ensuring no
single point of failure or control.
</p>
<p>
What makes Nostr uniquely resilient is its design, the protocol itself is just a set of rules, not a company or product that can disappear. Your Git issues, patches, and comments persist as long as relays choose to store them,
immune to the whims of corporate shutdowns or policy changes. Nostr is infrastructure in its purest form, an idea that outlives any temporary implementation. n34 taps into a future-proof foundation for decentralized collaboration.
</p>
<div class="links">
<h3>More about Nostr</h3>
<ul>
<li><a href="https://nostr.com">nostr.com</a></li>
<li><a href="https://nostr.org">nostr.org</a></li>
<li><a href="https://nostr.how/en/what-is-nostr">nostr.how/en/what-is-nostr</a></li>
</ul>
</div>
</div>
<div class="footer">
<p>Built with ❤️ for the decentralized future</p>
</div>
</div>
</body>
</html>

15
docs/issue/README.md Normal file
View File

@@ -0,0 +1,15 @@
# Issue Management
Using `n34`, you can manage Git issues stored in Nostr relays, adhering to
the [NIP-34] standard. In Nostr, events are immutable, meaning their IDs are
derived from the SHA-256 hash of their timestamp, content, author, and tags.
As a result, issues cannot be edited directly. However, with `n34`, you can
create new issues, view existing ones, or update their status—such as closing,
resolving, or reopening them.
[NIP-34] introduces support for drafting issues, though this feature is not
currently implemented in `n34` due to the lack of a clear use case for drafting
issues. The inclusion of this functionality may stem from its shared use in both
issues and patches, suggesting it was primarily designed for patch management.
[NIP-34]: https://github.com/nostr-protocol/nips/blob/master/34.md

19
docs/issue/close.md Normal file
View File

@@ -0,0 +1,19 @@
# Closes an Open Issue
> `n34 issue close` command
**Usage:**
```
Closes an open issue
Usage: n34 issue close [OPTIONS] <ISSUE_ID>
Arguments:
<ISSUE_ID> The open issue id to close 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`
```
Issue a kind `1632` (Close status) for the specified issue. The issue have to
be open.

19
docs/issue/list.md Normal file
View File

@@ -0,0 +1,19 @@
# List Repositories Issues
> `n34 issue list` command
**Usage:**
```
List the repositories issues
Usage: n34 issue 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 issues to list [default: 15]
```
List the repositories issues. By default `n34` will look for `nostr-address`
file and extract the repositories from it.

29
docs/issue/new.md Normal file
View File

@@ -0,0 +1,29 @@
# Create an Issue
> `n34 issue new` Command
**Usage:**
```
Create a new repository issue
Usage: n34 issue new [OPTIONS] <--content <CONTENT>|--editor>
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`
-c, --content <CONTENT> Markdown content for the issue. Cannot be used together with the `--editor` flag
-e, --editor Opens the user's default editor to write issue content. The first line will be used as the issue subject
--subject <SUBJECT> The issue subject. Cannot be used together with the `--editor` flag
-l, --label <LABEL> Labels for the issue. Can be specified as arguments (-l bug) or hashtags in content (#bug)
```
Use the `n34 issue new` command to create a new issue in a repository. This
command supports the [NIP-21] (`nostr:` URI scheme) and hashtags within the
issue content. When you mention public keys in the content, they will be
included in the event tags. Additionally, using hashtags like `#bug` in the
issue body will automatically apply them as labels.
You must choose between the `--content` and `--editor` options. With
`--content`, you provide the issue content directly in the command. With
`--editor`, your default `$EDITOR` will open, allowing you to write the issue
content. The first line of the editor's output will be used as the issue
subject.

19
docs/issue/reopen.md Normal file
View File

@@ -0,0 +1,19 @@
# Reopen a Closed Issue
> `n34 issue reopen` command
**Usage:**
```
Reopens a closed issue
Usage: n34 issue reopen [OPTIONS] <ISSUE_ID>
Arguments:
<ISSUE_ID> The ID of the closed issue to reopen
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 `1630` (Open status) for the specified issue. The issue have to
be closed.

18
docs/issue/resolve.md Normal file
View File

@@ -0,0 +1,18 @@
# Resolves an Issue
> `n34 issue resolve` command
**Usage:**
```
Resolves an issue
Usage: n34 issue resolve [OPTIONS] <ISSUE_ID>
Arguments:
<ISSUE_ID> The issue id to resolve 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`
```
Issue a kind `1631` (Resolved status) event for the specified issue.

19
docs/issue/view.md Normal file
View File

@@ -0,0 +1,19 @@
# View an Issue By ID
> `n34 issue view` command
**Usage:**
```
View an issue by its ID
Usage: n34 issue view [OPTIONS] <ISSUE_ID>
Arguments:
<ISSUE_ID> The issue id to view 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`
```
Simply provide the issue ID in `note` or `nevent` format to retrieve and display
the issue details.

21
docs/patch/README.md Normal file
View File

@@ -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`.

30
docs/patch/apply.md Normal file
View File

@@ -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'`.

20
docs/patch/close.md Normal file
View File

@@ -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.

19
docs/patch/draft.md Normal file
View File

@@ -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.

21
docs/patch/fetch.md Normal file
View File

@@ -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.

20
docs/patch/list.md Normal file
View File

@@ -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.

28
docs/patch/merge.md Normal file
View File

@@ -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

20
docs/patch/reopen.md Normal file
View File

@@ -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.

22
docs/patch/send.md Normal file
View File

@@ -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.

28
docs/reply.md Normal file
View File

@@ -0,0 +1,28 @@
# Reply to Issues and Patches
> `n34 reply` command
**Usage:**
```
Reply to issues and patches
Usage: n34 reply [OPTIONS] <--comment <COMMENT>|--editor> <nevent1-or-note1>
Arguments:
<nevent1-or-note1> The issue, patch, or comment to reply to
Options:
--quote-to Quote the replied-to event in the editor
--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`
-c, --comment <COMMENT> The comment (cannot be used with --editor)
-e, --editor Open editor to write comment (cannot be used with --content)
```
Craft replies ([NIP-22] Comment) to issues, patches, or comments with ease
using the `n34 reply` command. You can either input your reply directly with
the `--comment` option or open an editor for a more detailed response using
`--editor`. Additionally, when using `--editor`, the `--quote-to` option
allows you to include the original content in your editor, enabling precise and
context-aware replies.
[NIP-22]: https://github.com/nostr-protocol/nips/blob/master/22.md

4
docs/repo/README.md Normal file
View File

@@ -0,0 +1,4 @@
# Manage Repositories
In `n34` you can manage your repositories. This includes announcing new ones,
viewing existing ones, and announcing state updates (coming soon).

32
docs/repo/announce.md Normal file
View File

@@ -0,0 +1,32 @@
# Broadcast and Update a Git Repository
> `n34 repo announce` command
**Usage:**
```
Publish information about a git repository to Nostr for collaboration and feedback. Can also be used to update an existing repository's details
Usage: n34 repo announce [OPTIONS] --id <REPO_ID>
Options:
--id <REPO_ID> Unique identifier for the repository in kebab-case
-n, --name <NAME> A name for the repository
-d, --description <DESCRIPTION> A description for the repository
-w, --web <WEB> Webpage URLs for the repository (if provided by the git server)
-c, --clone <CLONE> URLs for cloning the repository
-m, --maintainers <MAINTAINERS> Additional maintainers of the repository (besides yourself)
-l, --label <LABEL> Labels to categorize the repository. Can be specified multiple times
--force-id Skip kebab-case validation for the repository ID
--address-file If set, creates a `nostr-address` file to enable automatic address discovery by n34
```
This command generates an announcement event to publish your project. It can be
used to announce a new repository or update an existing one.
When updating, you must resubmit all repository fields, not just the fields
you wish to change. The command uses this information to build and publish a
completely new announcement event that will replace the old one.
It is recommended to use the `--address-file` flag. This option creates
a `nostr-address` file that enables `n34` to automatically discover the
repository's address, simplifying the workflow for contributors.

20
docs/repo/view.md Normal file
View File

@@ -0,0 +1,20 @@
# View Git Repository Details
> `n34 repo view` command
**Usage:**
```
View details of a nostr git repository
Usage: n34 repo view [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`
```
This command prints repository details to standard output. If no arguments
are provided, it looks for a `nostr-address` file in the current directory
and displays the details for the address specified within it. See [passing
repositories] for details on accepted formats.
[passing repositories]: /commands.html#passing-repositories

11
docs/sets/README.md Normal file
View File

@@ -0,0 +1,11 @@
# Managing Repository and Relay Sets
Sets are a convenience feature for contributing to projects that do not have a
`nostr-address` file. Instead of manually specifying the project's repositories
and relays for every command, you can define them once as a named "set". You can
then reference this set by its name in commands. This allows you to use the set
as a shortcut for a list of relays (`--relays <set_name>`) or as the project's
address in commands like `issue` and `patch`.
Sets are defined in your configuration file. To use a specific configuration
file, pass its path using the `--config` option.

25
docs/sets/new.md Normal file
View File

@@ -0,0 +1,25 @@
# Create a Set
> `n34 sets new` command
**Usage:**
```
Create a new set
Usage: n34 sets new [OPTIONS] <NAME>
Arguments:
<NAME> Unique name for the set
Options:
--set-relay <RELAYS> Optional relay to add it to the set, either as URL or set name to extract its relays. [aliases: `--sr`]
--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`
```
Each set requires a unique name, provided as the final argument to the command.
Use the `--set-relays`/`--sr` option to specify the relays for the new set;
this can be a relay URL or the name of an existing set whose relays you wish to
use. To add repositories, use the `--repo` option. Check [passing repositories]
format.
[passing repositories]: /commands.html#passing-repositories

24
docs/sets/remove.md Normal file
View File

@@ -0,0 +1,24 @@
# Remove a Set
> `n34 sets remove` command
**Usage:**
```
Remove a set, or specific repos and relays within it
Usage: n34 sets remove [OPTIONS] <NAME>
Arguments:
<NAME> Set name to delete
Options:
--set-relay <RELAYS> Specific relay to remove it from the set, either as URL or set name to extract its relays. [aliases: `--sr`]
--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`
```
Removes an entire set, or specific repositories and relays from it.
Without options, this command deletes the entire set.
See the [passing repositories] section for more details on supported formats.
[passing repositories]: /commands.html#passing-repositories

17
docs/sets/show.md Normal file
View File

@@ -0,0 +1,17 @@
# Show a Set
> `n34 sets show` command
**Usage:**
```
Show a single set or all the stored sets
Usage: n34 sets show [NAME]
Arguments:
[NAME] Name of the set to display. If not provided, lists all available sets
```
Prints all set names to standard output, each followed by its associated repos
and relays. To view the details for a specific set, provide its name as an
argument.

25
docs/sets/update.md Normal file
View File

@@ -0,0 +1,25 @@
# Modify a Set
> `n34 sets update` command
**Usage:**
```
Modify an existing set
Usage: n34 sets update [OPTIONS] <NAME>
Arguments:
<NAME> Name of the set to update
Options:
--set-relay <RELAYS> Add relay to the set, either as URL or set name to extract its relays. [aliases: `--sr`]
--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`
--override Replace existing relays/repositories instead of adding to them
```
Use this command to update an existing set by its name. By default, providing
relays via `--set-relay` or repositories via `--repo` will add them to the set's
existing entries. To replace the current relays and repositories with the new
values, use the `--override` flag.
[passing repositories]: /commands.html#passing-repositories

1
flake.nix
View File

@@ -26,6 +26,7 @@
dbus dbus
git-cliff git-cliff
just just
mdbook
pkg-config pkg-config
taplo taplo
]; ];

20
justfile
View File

@@ -12,7 +12,7 @@ set script-interpreter := ["/usr/bin/env", "bash"]
JUST_EXECUTABLE := "just -u -f " + justfile() JUST_EXECUTABLE := "just -u -f " + justfile()
header := "Available tasks:\n" header := "Available tasks:\n"
# Get the MSRV from the Cargo.toml BOOK_DEST_DIR := "dest"
tag_change_body := '''{% for group, commits in commits | group_by(attribute="group") %} tag_change_body := '''{% for group, commits in commits | group_by(attribute="group") %}
{{ group | upper_first }} {{ group | upper_first }}
@@ -75,3 +75,21 @@ release version:
git tag -s -m "$TAG_MSG" "v{{ version }}" git tag -s -m "$TAG_MSG" "v{{ version }}"
git push origin master --tags git push origin master --tags
cargo publish cargo publish
# Deploy the book to Github Pages
[script]
deploy:
mdbook build --dest-dir {{ BOOK_DEST_DIR }}
cd {{ BOOK_DEST_DIR }}
git init .
git checkout -B gh-pages
touch .nojekyll
echo "n34.dev" > CNAME
git add .
git commit -m "Deploy the book to github pages"
git remote add origin "git@github.com:TheAwiteb/n34-book"
git push origin gh-pages -f
cd ..
rm -fr {{ BOOK_DEST_DIR }}