Radish alpha
h
heartwood
Radicle Heartwood Protocol & Stack
Radicle
Git (anonymous pull)
Log in to clone via SSH
Commits ›
cli: add workflow example with two peers
Slack Coder committed 3 years ago
commit b6c1560a0a40ec76d3efc6349d806d26b855b99c
parent d331389ada13decc046efa655410d52ec27d996f
8 files changed +376 -2
modified .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
modified 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!'
added 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
+ 
```
added 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
+ 
```
added 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
+ 
```
added 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
+ 
```
added 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 🌱
+
+ 
```
modified 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();
+ 
}