Fixed typos and grammar in Protocol & Seeders guides — radicle.xyz

radicle.xyz

rad:z371PVmDHdjJucejRoRYJcDEvD5pp

Radicle website including documentation and guides

Fixed typos and grammar in Protocol & Seeders guides

Merged did:key:z6Mkw1Yy...qkRm opened 2 years ago

protocol guide: fixed typos and grammar
seeders guide: fixed typos and grammar
protocol guide: advertize->advertise
protocol guide: cleaned up the COB description to reduce repetition

Activity Changes +38 -36

2 files changed +38 -36 d9b06ec8 → 3d2ad0dd

modified _guides/protocol.md

@@ -6,8 +6,8 @@ layout: guide

 Heartwood, the latest generation of the [Radicle][] protocol establishes a
 sovereign data network for code collaboration and publishing, built on top of
 [Git][]. In Radicle, users maintain local copies of their interested
 repositories and related social artifacts such as issues and patches. Instead
 [Git][]. In Radicle, users maintain local copies of their repositories of
 interest and related social artifacts such as issues and patches. Instead
 of depending on a centralized service like GitHub, each participant in Radicle
 operates a node that is capable of running on a personal computer, and is
 connected via a peer-to-peer network.

@@ -40,7 +40,7 @@ project coordination, and data set collaboration.

 Git, the most widely-used distributed version control system, enables users to
 maintain and modify personal copies of data repositories, commonly for source
 code control. Its structure for direct user-to-user collaboration, while
 feasible, is often cumbersome due to Git's primary focus on version control
 feasible, is often cumbersome since Git primarily focuses on version control
 rather than collaboration. As a result, users frequently opt for centralized
 [forges][] like GitHub or GitLab, which offer enhanced interfaces and
 collaborative tools on top of Git, such as project management and code review.

@@ -48,7 +48,7 @@ This dependency, however, can result in vendor lock-in since it places a

 project's social artifacts (e.g. issues, comments, pull requests) out of user
 control, potentially compromising data sovereignty and other user freedoms.
 Traditional self-hosted options like [Gitea][] or [Forgejo][] provide more
 Traditional self-hosted forges like [Gitea][] or [Forgejo][] provide more
 sovereignty but often lead to fragmented collaboration environments, as users
 must create separate profiles for each hosted instance. This simultaneously
 limits a project's exposure to the wider open source community, a key advantage

@@ -195,7 +195,7 @@ of failure, allowing the network to persist as long as users operate nodes.

 The Radicle networking layer is designed as a gossip protocol, where messages
 are relayed between peers to build routing tables that aid in repository
 discovery and replication. The core functionality is achieved with three
 message types, each fulfulling a distinct role:
 message types, each fulfilling a distinct role:
 **Node Announcements** are used for broadcasting Node IDs and physical
    addresses on which a node is publicly reachable, to facilitate peer

@@ -203,7 +203,7 @@ message types, each fulfulling a distinct role:

 | Node Announcement
 | -----------------
 | **`features`**  | `u64`            | Advertized node capabilities
 | **`features`**  | `u64`            | Advertised node capabilities
 | **`timestamp`** | `u64`            | Message timestamp (unix time)
 | **`alias`**     | `u8[]`           | Non-unique alias (UTF-8)
 | **`addresses`** | `Address[]`      | External addresses

@@ -268,7 +268,7 @@ connection the <em>initiator</em>. </aside>

 </figure>
 Once the static key is known, a connection to the node can be initiated
 securely, by generating an ephemral key from the static key, using
 securely, by generating an ephemeral key from the static key, using
 Diffie-Hellman. The last step involves the initiating node sending its own
 static key over the secure channel.

@@ -317,8 +317,8 @@ href="https://en.wikipedia.org/wiki/Multiplexing">multiplexing</a>. </aside>

 A node joining the network for the first time will not know any peers. Hence,
 it's useful to pre-configure network clients with addresses of well-known nodes
 that can be used to bootstrap the peer discovery process and build an address
 book.
 that can be used to initiate or *bootstrap* the peer discovery process and build
 an address book.
 Radicle's reference implementation is pre-configured with two [bootstrap
 nodes][bootstrap] that are connected to if the address book is empty:

@@ -326,7 +326,7 @@ nodes][bootstrap] that are connected to if the address book is empty:

 Radicle team and have large address books that are shared with connecting
 peers.
 In the bootstrapping process, nodes connect to an initial set of bootrap nodes
 In the bootstrapping process, nodes connect to an initial set of bootstrap nodes
 and once they establish a connection, use the regular peer discovery mechanism
 to find more peers.

@@ -466,7 +466,7 @@ document. This is then encoded using [multibase][mb] encoding with the

   <figcaption>Example Repository ID for the heartwood project.</figcaption>
 </figure>
 Since the RID is derived from the *initial* verison of the repository's identity
 Since the RID is derived from the *initial* version of the repository's identity
 document, the document is able to change while the RID remains the same.
 [urn]: https://datatracker.ietf.org/doc/html/rfc8141

@@ -658,7 +658,7 @@ all Git references published to the network.

 #### Signed Refs
 To enable the verification of Git references beyond commits to the source code,
 Radicle automatically signs the entirety of a node's references everytime they
 Radicle automatically signs the entirety of a node's references every time they
 change. This signature is then placed in a Git blob under a special branch
 referenced under `refs/rad/sigrefs`, along with the references that were signed.

@@ -782,14 +782,15 @@ Radicle's predefined COB types are stored under the `refs/cobs` hierarchy.

 These are associated with unique namespaces, such as `xyz.radicle.issue` and
 `xyz.radicle.patch`, to prevent naming collisions.
 For example, if a user or organization were to define a new COB type under
 their domain, it might look something like `com.acme.task`, for some
 hypothetical "task" COB under the `acme.com` domain.
 This hierarchical arrangement under `refs/cobs` not only houses Radicle's
 predefined COBs but also accommodates user-defined ones. For example, if a user
 or organization were to define a new COB type under their domain, it might look
 something like `com.acme.task`, for some hypothetical "task" COB under the
 `acme.com` domain.
 COBs are stored under the `refs/cobs` hierarchy, where Radicle's built-in COBs
 co-exist with user-defined COBs. This extensibility allows for an unlimited set
 of new collaboration primitives to be defined by users, without requiring
 coordination with the broader network or user-base.
 This extensibility allows for an unlimited set of new collaboration primitives
 to be defined by users, without requiring coordination with the broader network
 or user-base.
 ## Conclusion

modified _guides/seeder.md

@@ -7,7 +7,7 @@ layout: guide

 To seed is to give back. By seeding repositories on the Radicle network, you
 offer bandwidth, storage, and data availability to Radicle users.
 In this guide, we'll go through the various steps required to setup a Radicle
 In this guide, we'll go through the various steps required to set up a Radicle
 *seed node* on a Linux system. Seeding only requires an internet
 connection, a public, static IP address, and modest hardware.

@@ -21,9 +21,10 @@ The term *seed node* originally comes from [BitTorrent][bittorrent]. In the

 BitTorrent protocol, nodes that possess the data for a given torrent file
 and begin uploading it to peers are called *seeders*.
 In Radicle, a seed node is typically a server that is accessible through
 the internet and hosts content for peers. Seed nodes need to remain online
 and accessible to provide their service to the network.
 In Radicle, while all users contribute to the network by seeding data, the term
 *seed node* specifically refers to a server that is accessible through the
 internet and hosts content for peers. Seed nodes need to remain online and
 accessible to provide their service to the network.
 ### The Need for Seed Nodes

@@ -52,16 +53,16 @@ To run a Radicle seed node, you will need a server with:

 * `curl`
 * `git`
 * `systemctl` version `232` or newer
 * `sudo` priviledges
 * `sudo` privileges
 * A DNS name pointing to your server
 ### Server
 If you already have a VPS (Virtual Private Server) or home server running a
 Linux distribution, you should be all set. If not, any VPS will do. Between 1
 and 2GB of RAM with a shared CPU and 10GB of disk space should be enough to get
 started. Once you've logged into your server, proceed with user setup and
 installation. For this setup, you'll need `sudo` capabilities.
 Linux distribution, you should be all set. If not, any VPS will do. Between 1-2GB
 of RAM with a shared CPU and 10GB of disk space should be enough to get started.
 Once you've logged into your server, proceed with user setup and installation.
 For this setup process, you'll need `sudo` capabilities.
 > **Tip**: If you have trouble choosing a VPS, we recommend getting a small
 > instance on [Hetzner][hetzner] or [Digital Ocean][do]. These are priced

@@ -114,7 +115,7 @@ Radicle home is with the `rad path` command.

 To offer web browsing and HTTP access to your seed node, you will additionally
 need to run `radicle-httpd`, the HTTP daemon. We'll cover this after we've
 setup our basic node.
 set up our basic node.
 ### Creating a profile

@@ -128,7 +129,7 @@ The above command will create a profile with the given node *alias* in

 `~/.radicle`, or `$RAD_HOME` if set. We recommend setting your alias to the
 domain name that points to your node's host.
 For seed nodes, it's not generally necessary to setup a passphrase for your
 For seed nodes, it's not generally necessary to set up a passphrase for your
 key, so you can simply skip that prompt by pressing *enter*.
 <aside>

@@ -149,7 +150,7 @@ You can view information about your Radicle profile by running `rad self`. The

 Configuring your node
 ---------------------
 There are a couple of things we need to configure to setup a seed node.
 There are a couple of things we need to configure to set up a seed node.
 First, we must set the node's default *seeding policy*.

@@ -158,7 +159,7 @@ and offer to the network. For public seed nodes, a permissive seeding policy

 is often set, such that all data on the network is stored and replicated.
 Second, we must set an external address for the node to be reached on the
 network. This address will be advertized to peers, allowing them to connect to
 network. This address will be advertised to peers, allowing them to connect to
 your seed node. Generally, this will be a DNS name with port `8776`, for
 example `seed.mentharos.net:8776`.

@@ -235,7 +236,7 @@ you'll have to run all commands via `sudo`, eg. `sudo -u seed -- rad self`.

 ### Configuring your node as a system service
 Though it's possible to simply run the Radicle node as a background process,
 it's recommended to setup a service to ensure the node is started on boot.
 it's recommended to set up a service to ensure the node is started on boot.
 In this guide, we will only cover setup using `systemd`, but the process is
 fairly similar for other service managers.

@@ -386,7 +387,7 @@ simply enter `rad seed` with no options. This will list all configured policies.

 Configuring the HTTP backend
 ----------------------------
 In the sections above, we setup `radicle-node`, a background process that
 In the sections above, we set up `radicle-node`, a background process that
 actively and continuously discovers and replicates repositories on the network,
 based on your seeding policy. This node allows users to collaborate, host,
 share and publish repositories on the network via the Radicle CLI or any

@@ -448,7 +449,7 @@ Then, download the `caddy` unit file from Caddy's GitHub repository:

 Edit the file and change the `User` and `Group` attributes to `seed`, as we
 have for the other services. Also ensure that `ExecStart` and `ExecReload`
 are set to the correct path. You can find the path under which `caddy` is
 installed by entering `which caddy`.
 installed by running the `which caddy` command.
 Finally, edit or create the `Caddyfile` at `/etc/caddy/Caddyfile`, and replace
 its contents with the following configuration, using the correct domain name

@@ -478,7 +479,7 @@ well. For example, <https://app.radicle.xyz/nodes/seed.mentharos.net>.

 ### You're all set
 If you got this far, congratulations, you have a Radicle seed node all setup
 If you got this far, congratulations, you now have a Radicle seed node up
 and running!
 🎊👾