diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index a2fd240a..8723739a 100644 --- a/.github/workflows/ci.yaml +++ b/.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 diff --git a/radicle-cli/examples/rad-patch.md b/radicle-cli/examples/rad-patch.md index 921c5455..104abe89 100644 --- a/radicle-cli/examples/rad-patch.md +++ b/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!' diff --git a/radicle-cli/examples/workflow/1-new-project.md b/radicle-cli/examples/workflow/1-new-project.md new file mode 100644 index 00000000..ef5255f1 --- /dev/null +++ b/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 +``` diff --git a/radicle-cli/examples/workflow/2-cloning.md b/radicle-cli/examples/workflow/2-cloning.md new file mode 100644 index 00000000..70ed7ca6 --- /dev/null +++ b/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 +Date: Mon Jan 1 14:39:16 2018 +0000 + + Second commit +``` diff --git a/radicle-cli/examples/workflow/3-issues.md b/radicle-cli/examples/workflow/3-issues.md new file mode 100644 index 00000000..c58b2e98 --- /dev/null +++ b/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 +``` diff --git a/radicle-cli/examples/workflow/4-patching-contributor.md b/radicle-cli/examples/workflow/4-patching-contributor.md new file mode 100644 index 00000000..97926857 --- /dev/null +++ b/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 +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 +``` diff --git a/radicle-cli/examples/workflow/5-patching-maintainer.md b/radicle-cli/examples/workflow/5-patching-maintainer.md new file mode 100644 index 00000000..ff25a8d8 --- /dev/null +++ b/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 🌱 + +``` diff --git a/radicle-cli/tests/commands.rs b/radicle-cli/tests/commands.rs index 85679899..137352d6 100644 --- a/radicle-cli/tests/commands.rs +++ b/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(); +}