cli: add workflow example with two peers

Make the documentation more realistic by using two peers, a maintainer
and a contributor, for the client examples.  Define them as 'workflow'
examples, ordering them in their own directory to aid user navigation.

.github/workflows/ci.yaml

@@ -29,6 +29,7 @@ jobs:
           # integration testing.
           cargo install --locked --debug --path ./radicle-remote-helper
           cargo test --all --all-features rad_patch -- --ignored
+          cargo test --all --all-features rad_workflow -- --ignored
 
   docs:
     name: Docs

radicle-cli/examples/rad-patch.md

@@ -75,7 +75,7 @@ index 0000000..e69de29
 
 ```
 
-Wait, lets add a README too! Just for fun.
+Wait, let's add a README too! Just for fun.
 
 ```
 $ touch README.md
@@ -99,7 +99,7 @@ $ rad patch update --message "Add README, just for the fun" 191a14e520f2eeff7c0e
 
 ```
 
-And lets leave a quick comment for our team:
+And let's leave a quick comment for our team:
 
 ```
 $ rad comment 191a14e520f2eeff7c0e3ee0a5523c5217eecb89 --message 'I cannot wait to get back to the 90s!'

radicle-cli/examples/workflow/1-new-project.md

@@ -0,0 +1,30 @@
+To create your first radicle project, navigate to a git repository, and run the
+`init` command.  Make sure you have [created your user and authenticated](../rad-auth.md)
+beforehand!
+
+```
+$ rad init --name heartwood --description "Radicle Heartwood Protocol & Stack" --no-confirm --no-track -v
+
+Initializing local 🌱 project in .
+
+✓ Project heartwood created
+{
+  "name": "heartwood",
+  "description": "Radicle Heartwood Protocol & Stack",
+  "defaultBranch": "master"
+}
+
+Your project id is rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji. You can show it any time by running:
+    rad .
+
+To publish your project to the network, run:
+    rad push
+
+```
+
+Projects can be listed with the `ls` command:
+
+```
+$ rad ls
+heartwood rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji f2de534 Radicle Heartwood Protocol & Stack
+```

radicle-cli/examples/workflow/2-cloning.md

@@ -0,0 +1,56 @@
+To create a local copy of a repository on the radicle network, we use the
+`clone` command, followed by the identifier or *RID* of the repository:
+
+```
+$ rad clone rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji
+✓ Tracking relationship established for rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji
+✓ Fetching rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji from z6MknSL…StBU8Vi..
+✓ Forking under z6Mkt67…v4N1tRk..
+✓ Creating checkout in ./heartwood..
+✓ Remote z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi created
+✓ Remote-tracking branch z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi/master created for z6MknSL…StBU8Vi
+
+🌱 Project successfully cloned under [..]/heartwood/
+
+```
+
+We can now have a look at the new working copy that was created from the cloned
+repository:
+
+```
+$ cd heartwood
+$ ls
+README
+$ cat README
+Hello World!
+```
+
+Let's check that the remote tracking branch was setup correctly:
+
+```
+$ git branch --remotes
+  rad/master
+  z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi/master
+```
+
+The first branch is ours, and the second points to the repository delegate.
+We can also take a look at the remotes:
+
+```
+$ git remote -v
+rad	rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk (fetch)
+rad	rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk (push)
+z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi	rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi (fetch)
+z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi	rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi (push)
+```
+
+Finally, let's inspect the last commit!
+
+```
+$ git log -n 1
+commit f2de534b5e81d7c6e2dcaf58c3dd91573c0a0354
+Author: anonymous <anonymous@radicle.xyz>
+Date:   Mon Jan 1 14:39:16 2018 +0000
+
+    Second commit
+```

radicle-cli/examples/workflow/3-issues.md

@@ -0,0 +1,51 @@
+Project "todos" are called *issues*.  They can be inspected and
+modified using the `issue` subcommand.
+
+Let's say the new car you are designing with your peers has a problem with its flux capacitor.
+
+```
+$ rad issue open --title "flux capacitor underpowered" --description "Flux capacitor power requirements exceed current supply" --no-announce
+title: flux capacitor underpowered
+state: open
+tags: []
+assignees: []
+
+Flux capacitor power requirements exceed current supply
+```
+
+The issue is now listed under our project.
+
+```
+$ rad issue list
+b05e945bb63c11bf80320f4e26ad1d1f7c51f755 "flux capacitor underpowered"
+```
+
+Great! Now we've documented the issue for ourselves and others.
+
+Just like with other project management systems, the issue can be assigned to
+others to work on.  This is to ensure work is not duplicated.
+
+Let's assign this issue to ourself.
+
+```
+$ rad assign b05e945bb63c11bf80320f4e26ad1d1f7c51f755 --to did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk
+```
+
+It will now show in the list of issues assigned to us.
+
+```
+$ rad issue list --assigned
+b05e945bb63c11bf80320f4e26ad1d1f7c51f755 "flux capacitor underpowered" did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk
+```
+
+Note: this can always be undone with the `unassign` subcommand.
+
+Great, now we have communicated to the world about our car's defect.
+
+But wait! We've found an important detail about the car's power requirements.
+It will help whoever works on a fix.
+
+```
+$ rad comment b05e945bb63c11bf80320f4e26ad1d1f7c51f755 --message 'The flux capacitor needs 1.21 Gigawatts'
+8b9ee0f0a530f0318e100ea8b9ed3a723bd584f6
+```

radicle-cli/examples/workflow/4-patching-contributor.md

@@ -0,0 +1,107 @@
+When contributing to another's project, it is common for the contribution to be
+of many commits and involve a discussion with the project's maintainer.  This is supported
+via Radicle *patches*.
+
+Here we give a brief overview for using patches in our hypothetical car
+scenario.  It turns out instructions containing the power requirements were
+missing from the project.
+
+```
+$ git checkout -b flux-capacitor-power
+$ touch REQUIREMENTS
+```
+
+Here the instructions are added to the project's `REQUIREMENTS` for 1.21
+gigawatts and committed with git.
+
+```
+$ git add REQUIREMENTS
+$ git commit -v -m "Define power requirements"
+[flux-capacitor-power 3e674d1] Define power requirements
+ 1 file changed, 0 insertions(+), 0 deletions(-)
+ create mode 100644 REQUIREMENTS
+```
+
+Once the code is ready, we open a patch with our changes.
+
+```
+$ rad patch open --message "Define power requirements" --message "See details."
+✓ Pushing HEAD to storage...
+✓ Analyzing remotes...
+
+master <- z6Mkt67…v4N1tRk/flux-capacitor-power (3e674d1)
+
+1 commit(s) ahead, 0 commit(s) behind
+
+3e674d1 Define power requirements
+
+✓ Patch a07ef7743a32a2e902672ea3526d1db6ee08108a created 🌱
+
+To publish your patch to the network, run:
+    rad push
+
+```
+
+It will now be listed as one of the project's open patches.
+
+```
+$ rad patch
+
+❲YOU PROPOSED❳
+
+Define power requirements a07ef7743a3 R0 3e674d1 (flux-capacitor-power) ahead 1, behind 0
+└─ * opened by did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk (you) [..]
+└─ * patch id a07ef7743a32a2e902672ea3526d1db6ee08108a
+
+❲OTHERS PROPOSED❳
+
+Nothing to show.
+
+$ rad patch show a07ef7743a32a2e902672ea3526d1db6ee08108a
+
+Define power requirements
+
+See details.
+
+commit 3e674d1a1df90807e934f9ae5da2591dd6848a33
+Author: radicle <radicle@localhost>
+Date:   Thu Dec 15 17:28:04 2022 +0000
+
+    Define power requirements
+
+diff --git a/REQUIREMENTS b/REQUIREMENTS
+new file mode 100644
+index 0000000..e69de29
+
+```
+
+Wait, let's add a README too! Just for fun.
+
+```
+$ touch README.md
+$ git add README.md
+$ git commit --message "Add README, just for the fun"
+[flux-capacitor-power 27857ec] Add README, just for the fun
+ 1 file changed, 0 insertions(+), 0 deletions(-)
+ create mode 100644 README.md
+$ rad patch update --message "Add README, just for the fun" a07ef7743a32a2e902672ea3526d1db6ee08108a
+
+🌱 Updating patch for heartwood
+
+✓ Pushing HEAD to storage...
+✓ Analyzing remotes...
+
+a07ef7743a3 R0 (3e674d1) -> R1 (27857ec)
+1 commit(s) ahead, 0 commit(s) behind
+
+
+✓ Patch a07ef7743a32a2e902672ea3526d1db6ee08108a updated 🌱
+
+```
+
+And let's leave a quick comment for our team:
+
+```
+$ rad comment a07ef7743a32a2e902672ea3526d1db6ee08108a --message 'I cannot wait to get back to the 90s!'
+73b006df6f494e6fb9f9b9e8ad152091fc25db69
+```

radicle-cli/examples/workflow/5-patching-maintainer.md

@@ -0,0 +1,69 @@
+Back to being the project maintainer.
+
+Changes have been proposed by another person (or peer) via a radicle patch.  To follow changes by another, we must 'track' them.
+
+```
+$ rad track did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk --alias bob
+✓ Tracking policy updated for z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk (bob)
+! Warning: fetch after track is not yet supported
+$ rad fetch
+✓ Fetching rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji from z6Mkt67…v4N1tRk..
+✓ Fetched repository from 1 seed(s)
+```
+
+Additionally, we need to add a new 'git remote' to our working copy for the
+peer.  Upcoming versions of radicle will not require this step.
+
+```
+$ git remote add bob rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk
+$ git fetch bob
+```
+
+The contributor's changes are now visible to us.
+
+```
+$ git branch -r
+  bob/flux-capacitor-power
+  bob/master
+  rad/master
+$ rad patch
+
+❲YOU PROPOSED❳
+
+Nothing to show.
+
+❲OTHERS PROPOSED❳
+
+Define power requirements a07ef7743a3 R1 27857ec ahead 2, behind 0
+└─ * opened by did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk [..]
+└─ * patch id a07ef7743a32a2e902672ea3526d1db6ee08108a
+
+```
+
+Wait! There's a mistake.  The REQUIREMENTS should be a markdown file.  Let's
+quickly update the patch before incorporating the changes.  Updating it this
+way will tell others about the corrections we needed before merging the
+changes.
+
+```
+$ git checkout flux-capacitor-power
+branch 'flux-capacitor-power' set up to track 'bob/flux-capacitor-power'.
+$ git mv REQUIREMENTS REQUIREMENTS.md
+$ git commit --fixup HEAD~
+[flux-capacitor-power f6484e0] fixup! Define power requirements
+ 1 file changed, 0 insertions(+), 0 deletions(-)
+ rename REQUIREMENTS => REQUIREMENTS.md (100%)
+$ rad patch update --message "Define power requirements" --message "See details." a07ef7743a32a2e902672ea3526d1db6ee08108a
+
+🌱 Updating patch for heartwood
+
+✓ Pushing HEAD to storage...
+✓ Analyzing remotes...
+
+a07ef7743a3 R1 (27857ec) -> R2 (f6484e0)
+1 commit(s) ahead, 0 commit(s) behind
+
+
+✓ Patch a07ef7743a32a2e902672ea3526d1db6ee08108a updated 🌱
+
+```

radicle-cli/tests/commands.rs

@@ -546,3 +546,63 @@ fn test_replication_via_seed() {
         .remote(&bob.id)
         .unwrap();
 }
+
+#[test]
+#[ignore]
+fn rad_workflow() {
+    let mut environment = Environment::new();
+    let alice = environment.node("alice");
+    let bob = environment.node("bob");
+    let working = environment.tmp().join("working");
+
+    fixtures::repository(working.join("alice"));
+
+    test(
+        "examples/workflow/1-new-project.md",
+        &working.join("alice"),
+        Some(&alice.home),
+        [],
+    )
+    .unwrap();
+
+    let alice = alice.spawn(Config::default());
+    let mut bob = bob.spawn(Config::default());
+
+    bob.connect(&alice).converge([&alice]);
+
+    test(
+        "examples/workflow/2-cloning.md",
+        &working.join("bob"),
+        Some(&bob.home),
+        [],
+    )
+    .unwrap();
+
+    bob.connect(&alice).converge([&alice]);
+
+    test(
+        "examples/workflow/3-issues.md",
+        &working.join("bob").join("heartwood"),
+        Some(&bob.home),
+        [],
+    )
+    .unwrap();
+
+    test(
+        "examples/workflow/4-patching-contributor.md",
+        &working.join("bob").join("heartwood"),
+        Some(&bob.home),
+        [],
+    )
+    .unwrap();
+
+    bob.converge([&alice]);
+
+    test(
+        "examples/workflow/5-patching-maintainer.md",
+        &working.join("alice"),
+        Some(&alice.home),
+        [],
+    )
+    .unwrap();
+}