From f9678feb728d1abf9522b99d4375e816ae53cedc Mon Sep 17 00:00:00 2001
From: Jordan Doyle <jordan@doyle.la>
Date: Wed, 29 Sep 2021 18:08:32 +0100
Subject: [PATCH] Add user guide to the book

---
 book/src/getting-started/user-guide.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/book/src/getting-started/user-guide.md b/book/src/getting-started/user-guide.md
index cd3d452..4623393 100644
--- a/book/src/getting-started/user-guide.md
+++ a/book/src/getting-started/user-guide.md
@@ -1,1 +1,84 @@
 # User Guide
+
+Using chartered as a user is actually pretty simple, it's very much like your
+standard Cargo registry except with two extra concepts: organisations and
+permissions.
+
+Organisations are very much like the organisations you'll likely have used on
+your preferred SCM host, a group of users that have group-level permissions,
+in Chartered case the permissions these users may have are:
+
+### Permissions
+
+- `VISIBLE`
+    - Essentially the base-level permission meaning the user belongs to the group,
+      if the user doesn't have this permission they're not in the group, this
+      permission at the crate-level means the user can download the crate and see
+      it in the WebUI.
+- `PUBLISH_VERSION`
+    - Gives the ability to publish a new version for crates belonging to the group.
+- `YANK_VERSION`
+    - Gives the ability to yank (and unyank) published versions for crates belonging
+      to the group.
+- `MANAGE_USERS`
+    - Gives the ability to add (and remove) users from the group, and crates belonging
+      to the organisation.
+- `CREATE_CRATE`
+    - Gives the ability to create a new crate under the organisation.
+
+All these permissions, with the exception of `CREATE_CRATE`, can also be used at the
+crate-level for giving extra permissions to org members for a particular crate - or
+even users outside of the org. Bare in mind, however, these permissions are _additive_ -
+it is not possible for permissions to be _subtracted_ from a user at the crate-level
+if they have been granted them by the organisation.
+
+### Publishing your first crate
+
+With all this in mind, it's about time you started publishing your first crate!
+
+Chartered has excellent integration with Cargo's [alternative registry][arp]
+implementation and is used very much like a standard alternative registry. The only
+prerequisites for publishing your crate are:
+
+1. Have an SSH key added to your Chartered account, which you can do via the WebUI
+2. Belong to an organisation you have the `PUBLISH_VERSION` permission for, anyone can
+   create a new organisation if you don't already belong to one.
+
+And once you're ready, you can add the organisation's registry to your `.cargo/config.toml`
+like so:
+
+```toml
+[registries]
+my-organisation = { index = "ssh://ssh.your.instance.of.chart.rs/my-organisation" }
+```
+
+(You should create this file if it doesn't already exist)
+
+You can now publish the crate using cargo as you normally would, except with the
+registry specified:
+
+```sh
+$ cargo publish --registry my-organisation --token ""
+```
+
+Note: the token is purposefully empty, as the token will be vended by the index based
+on your SSH key.
+
+[arp]: https://doc.rust-lang.org/cargo/reference/registries.html
+
+### Pulling in dependencies
+
+Again, not too dissimilar from using [crates.io][cio], you can declare your dependencies
+as normal with the exception that you need to specify the organisation the crate should
+be pulled from provided you've declared the organisation in `.cargo/config.toml` as shown
+in the previous section of this guide.
+
+```toml
+[dependencies]
+my-other-crate = { version = "0.1", registry = "my-organisation" }
+```
+
+Your other Cargo dependencies from [crates.io][cio] can be declared as normal alongside
+organisation dependencies.
+
+[cio]: https://crates.io/
--
rgit 0.1.3