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.
This commit is contained in:
Slack Coder
Alexis Sellier
parent
d331389ada
commit
b6c1560a0a
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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!'
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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 🌱
|
||||
|
||||
```
|
||||
|
|
@ -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();
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue