From 57ef533ce5c0e0fd71f8f6f65458a849e3b7ab19 Mon Sep 17 00:00:00 2001 From: bill-auger Date: Jun 01 2022 01:49:07 +0000 Subject: update user-story examples --- diff --git a/doc/EXAMPLE_WORKFLOWS.md b/doc/EXAMPLE_WORKFLOWS.md index 6b6d1fc..610738b 100644 --- a/doc/EXAMPLE_WORKFLOWS.md +++ b/doc/EXAMPLE_WORKFLOWS.md @@ -5,70 +5,134 @@ Note that these are just some possible workflows implementations. Naturally, eac ``` Background: -Given: that fred.org and barney.net are public instances implementing the protocol above -And: user 'fred' creates an account on fred.org -And: user 'barney' creates an account on barney.net -And: user 'pebbles' creates an account on pebbles.info -Then: user 'fred' is assigned the globally unique ID: 'fred@fred.org' -And: user 'barney' is assigned the globally unique ID: 'barney@barney.net' -And: user 'pebbles' is assigned the globally unique ID: 'pebbles@pebbles.info' -Then: user 'fred' is assigned the repo URL namespace 'fred.org/fred/' -And: user 'barney' is assigned the repo URL namespace 'barney.net/barney/' -And: user 'pebbles' is assigned the repo URL namespace 'pebbles.info/pebbles/' -Then: user 'barney' creates a repo 'barney.net/barney/barney-made-this' +Given: 'fred.org' is Redmine tracker with VCS enabled, implementing the ForgeFed protocol partially +And: 'barney.net' is a complete forge, implementing the entire ForgeFed protocol +And: 'pebbles.me' is an Issue Tracker, implementing the ForgeFed protocol partially +Or: 'pebbles.me' is a Mastodon server, implementing the ForgeFed protocol minimally +Or: 'pebbles.me' is an email server, implementing the ForgeFed protocol minimally +Or: 'pebbles.me' is any custom peer, implementing the ForgeFed protocol minimally +And: fred creates an account on 'fred.org' +And: barney creates an account on 'barney.net' +And: pebbles creates an account on 'pebbles.me' +And: user 'fred' has permission to create new projects on 'fred.org' +Then: user 'fred' is assigned the globally unique ForgeFed ID: 'fred@fred.org' +And: user 'barney' is assigned the globally unique ForgeFed ID: 'barney@barney.net' +And: user 'pebbles' is assigned the globally unique ForgeFed ID: 'pebbles@pebbles.me' +When: barney creates a project: 'barney.net/barney/barney-made-this' +Then: the following scenarios may apply Scenario: user forks a foreign repo -When: fred visits the 'barney.net/barney/barney-made-this' -And: fred presses the 'fork' button -Then: fred is asked to enter (or select) the domain of his home-server -When: fred indicates the domain of his home-server as 'fred.org' -Then: fred is redirected to 'fred.org/login' which is a pass-through if he is already signed in -When: fred is authenticated -Then: the 'fred.org' server clones the 'barney-made-this repo' into fred's namespace -And: the 'fred.org' server posts a notification to the 'barney.net' server indicating that user 'fred@fred.org' has forked the repo 'barney/barney-made-this' -And: fred is redirected to 'fred.org/fred/barney-made-this' -And: the web page at 'fred.org/fred/barney-made-this' indicates it's parent fork with a link to 'barney.net/barney/barney-made-this' -And: the web page at 'barney.net/barney/barney-made-this/forks' indicates that it's child fork with a link to 'fred.org/fred/barney-made-this' - - -Scenario: user posts a merge request on a foreign repo -Given: that fred has forked 'barney.net/barney/barney-made-this' as 'fred.org/fred/barney-made-this' -And: fred has pushed new commits to his 'barney-made-this' fork -And: fred visits 'fred.org/fred/barney-made-this' -When: fred presses the 'merge request' button -Then: the 'fred.org' server posts a notification to the 'barney.net' server indicating that user 'fred@fred.org' has posted a merge request to the repo 'barney/barney-made-this' and that the commit data is accessible at 'fred.org/fred/barney-made-this.git#feature-branch' -And: the 'barney.net' server clones the repo 'fred.org/fred/barney-made-this.git#feature-branch' -And: the 'barney.net' server validates the pending merge status -And: the 'barney.net' server creates a 'PR' type issue -And: the 'barney.net' server adds the event to an 'unseen-alerts' db array for user 'barney' -And: the 'barney.net' server sends barney an email notification -And: the 'barney.net' server posts a notification to the 'fred.org' server confirming that the request initiated by user 'fred@fred.org' to create a 'PR' type issue was honored, and is accessible at the URL: 'barney.net/barney/barney-made-this/issues/42' -And: fred is redirected to the 'PR' type issue at 'barney.net/barney/barney-made-this/issues/42' (or perhaps fred's home-server implements it's fork's issues as a mirror of the upstream issues and directs fred to that URL - the beauty of federation is that, either implementation could be equivalent and transparent to users) - - -Scenario: user posts a comment on a foreign repo issue -Given: that an issue exists at 'barney.net/barney/barney-made-this/issues/42' -When: fred visits 'barney.net/barney/barney-made-this/issues/42' -And: fred fills the 'comment' textbox and presses the 'send' button -Then: fred is asked to enter (or select) the domain of his home-server -When: fred indicates the domain of his home-server as 'fred.org' -Then: fred is redirected to 'fred.org/login' which is a pass-through if he is already signed in +Given: that fred is not logged into 'barney.net' as a registered user of 'barney.net' +When: fred visits 'barney.net/barney/barney-made-this' +And: fred presses the 'fork' button +Then: fred is asked to enter (or select) the domain or IP of his home-server +When: fred indicates the home-server as 'fred.org' +Then: fred is redirected to 'fred.org/login' for authentication When: fred is authenticated -Then: the 'fred.org' server posts a notification addressed to the 'barney.net' server indicating that user 'fred@fred.org' has posted a comment to the repo issue at 'barney.net/barney/barney-made-this/issues/42' -And: the 'barney.net' server creates a new comment -And: the 'barney.net' server adds the event to an 'unseen-alerts' db array for user 'barney' -And: the 'barney.net' server sends barney an email notification -And: the 'barney.net' server posts a notification to the 'fred.org' server confirming that the request initiated by user 'fred@fred.org' to create an issue comment was honored, and is accessible at the URL: 'barney.net/barney/barney-made-this/issues/42#comment-2' -And: fred is redirected to the issue at 'barney.net/barney/barney-made-this/issues/42#comment-2' +Then: the 'fred.org' server creates a 'barney-made-this' project +And: the 'fred.org' server clones the 'barney.net/barney/barney-made-this.git' repo as 'fred.org/barney-made-this/barney-made-this.git' +And: the 'fred.org' server posts a request to the 'barney.net' server indicating that user 'fred@fred.org' has forked the repo 'barney/barney-made-this', which is accessible at the URL: 'fred.org/barney-made-this/barney-made-this.git' +When: the 'barney.net' server receives the fork request from the 'fred.org' server +Then: the web page at 'barney.net/barney/barney-made-this/forks' indicates fred's child fork, with a link to 'fred.org/barney-made-this' +And: the 'barney.net' server posts a request to the 'fred.org' server, acknowledging the fork +When: the 'fred.org' server receives the fork acknowledgment from the 'barney.net' server +Then: fred is redirected to 'fred.org/barney-made-this' +And: the web page at 'fred.org/barney-made-this' indicates it's parent fork, with a link to 'barney.net/barney/barney-made-this' + + +Scenario: user posts a merge request against a foreign repo +Given: that fred is logged into 'fred.org' +And: fred is not logged into 'barney.net' as a registered user of 'barney.net' +And: fred has forked 'barney.net/barney/barney-made-this' as 'fred.org/barney-made-this' +And: fred has pushed new commits to the 'feature-branch' branch of his 'barney-made-this' fork +And: fred visits 'fred.org/barney-made-this' +When: fred presses the 'merge request' button +Then: the 'fred.org' server posts a request to the 'barney.net' server indicating that user 'fred@fred.org' has posted a merge request against the repo 'barney/barney-made-this', and that the commit data is accessible at the URL: 'fred.org/barney-made-this/barney-made-this.git#feature-branch' +When: the 'barney.net' server receives the MR request from the 'fred.org' server +Then: the 'barney.net' server clones the repo 'fred.org/barney-made-this/barney-made-this.git', pending merge +And: the 'barney.net' server creates a 'MR' type ticket (e.g. #42) as 'barney.net/barney/barney-made-this/issues/42' +And: the 'barney.net' server posts a request to the 'fred.org' server, confirming that the request initiated by user 'fred@fred.org' to create a 'MR' type ticket was honored, and is accessible at the URL: 'barney.net/barney/barney-made-this/issues/42' +When: the 'fred.org' server receives the MR acknowledgment from the 'barney.net' server +Then: the 'fred.org' server replicates/mirrors the MR ticket #42 as 'fred.org/barney-made-this/42' +And: fred is redirected to 'fred.org/barney-made-this/42' + + +Scenario: user posts a comment on a foreign ticket +Given: that pebbles's service is not a web server, but exposes 'pebbles.me/login' over HTTP, to authenticate her web browser session, with a callback redirect to attest such to the foreign forge +And: a ticket exists at 'barney.net/barney/barney-made-this/issues/42' +When: pebbles visits 'barney.net/barney/barney-made-this/issues/42' +And: pebbles fills the 'comment' text-box and presses the 'send' button +Then: pebbles is asked to enter the domain or IP of her home-server +When: pebbles indicates the home-server as 'pebbles.me' +Then: pebbles is redirected to 'pebbles.me/login' for authentication +When: pebbles is authenticated +Then: the 'pebbles.me' server posts a request to the 'barney.net' server indicating that user 'pebbles@pebbles.me' has posted a comment to the ticket at 'barney.net/barney/barney-made-this/issues/42' +When: the 'barney.net' server receives the comment request from the 'pebbles.me' server +Then the 'barney.net' server creates a new comment #420 +And: the 'barney.net' server posts a request to the 'pebbles.me' server confirming that the request initiated by user 'pebbles@pebbles.me' to create a ticket comment was honored, and is accessible at the URL: 'barney.net/barney/barney-made-this/issues/42#comment-420' +When: the 'pebbles.me' server receives the comment acknowledgment from the 'barney.net' server +Then: pebbles is redirected to the ticket comment at 'barney.net/barney/barney-made-this/issues/42#comment-420' + +NOTE: that in the previous scenario pebbles's "server" is not necessarily a web server. + "server" means only "ForgeFed-compatible service". In order for this scenario to work, + + +Scenario: user posts a comment on a foreign ticket, using own home-server only +Given: that fred is logged into 'fred.org' +And: 'fred.org/barney-made-this/' is a child fork of 'barney.net/barney/barney-made-this' +And: fred visits 'fred.org/barney-made-this/42' +When: fred fills the 'comment' text-box and presses the 'post' button +Then: fred is optionally prompted for the remote fork, to which the comment should be posted +When: the remote fork is decided to be 'barney.net' (it may be implicit, if only one known fork exists) +Then: the 'fred.org' server posts a request to the 'barney.net' server indicating that user 'fred@fred.org' has posted a comment to the ticket at 'barney.net/barney/barney-made-this/issues/42' +When: the 'barney.net' server receives the comment request from the 'fred.org' server +Then: the 'barney.net' server creates a new comment #420 +And: the 'barney.net' server posts a request to the 'fred.org' server confirming that the request initiated by user 'fred@fred.org' to create a ticket comment was honored, and is accessible at the URL: 'barney.net/barney/barney-made-this/issues/42#comment-420' +When: the 'fred.org' server receives the comment acknowledgment from the 'barney.net' server +Then the 'fred.org' server replicates the comment #420 as 'fred.org/barney-made-this/42#comment-420' +And: fred sees the new comment as 'fred.org/barney-made-this/42#comment-420' + +NOTE: fred should not see the comment locally, unless/until barney.net acknowledges it +NOTE: fred may or may not be able to change the ticket state, edit/delete the comment, etc (the barney.net ACL governs that) +NOTE: that the previous scenario assumes that fred's issue tracker is a mirror, + synchronized with barney's tracker - it could of course be local-only, + independent of barney's tracker, in which case this scenario is not possible + + +Scenario: user posts a comment on a foreign ticket, without a web browser +Given: that pebbles's service is not a web server - it is a curl-based CLI client +And: a ticket exists at 'barney.net/barney/barney-made-this/issues/42' +When: pebbles fetches 'barney.net/barney/barney-made-this/issues' +Then: pebbles sees a reference to 'barney.net/barney/barney-made-this/issues/42' +When: pebbles selects that ticket, writes a comment, and saves the temporary file +Then: the 'pebbles.me' server posts a request to the 'barney.net' server indicating that user 'pebbles@pebbles.me' has posted a comment to the ticket at 'barney.net/barney/barney-made-this/issues/42' +When: the 'barney.net' server receives the comment request from the 'pebbles.me' server +Then the 'barney.net' server creates a new comment #420 +And: the 'barney.net' server posts a request to the 'pebbles.me' server confirming that the request initiated by user 'pebbles@pebbles.me' to create a ticket comment was honored, and is accessible at the URL: 'barney.net/barney/barney-made-this/issues/42#comment-420' + +NOTE: the astute reader will notice that this feature is ripe for spam; + but the same would be the case if pebbles's service was webby. + spam must always be anticipated in a publicly-writable federated system, + which accepts "self-registration" from anyone, as most forges do. Scenario: subscribed user receives notifications for important events -Given: that user 'pebbles@pebbles.info' has subscribed to the repo 'barney.net/barney/barney-made-this' -When: user 'fred@fred.org' creates a merge request at 'barney.net/barney/barney-made-this/issues/42' -Then: the 'barney.net' server posts a notification to the 'pebbles.info' server indicating that user 'fred@fred.org' has posted a merge request at 'barney.net/barney/barney-made-this/issues/42' -And: the 'pebbles.info' server adds the event to an 'unseen-alerts' db array for user 'pebbles' -And: the 'pebbles.info' server sends pebbles an email notification -When: pebbles visits 'pebbles.info/pebbles/notifications' -Then: pebbles sees a link to the PR issue from user 'fred@fred.org' 'barney.net/barney/barney-made-this/issues/42' +Given: the 'fred.org/barney-made-this' tracker is a synchronized replica of the 'barney.net/barney/barney-made-this' tracker +And: pebbles has subscribed to the project: 'fred.org/barney-made-this' +And: pebbles has also subscribed to the project: 'barney.net/barney/barney-made-this' +When: fred adds a comment to ticket: 'fred.org/barney-made-this/barney-made-this/issues/42' +Then: the 'fred.org' server posts a request to the 'barney.net' server indicating that user 'fred@fred.org' has posted a comment to the ticket at 'barney.net/barney/barney-made-this/issues/42' +When: the 'barney.net' server receives the comment request from the 'fred.org' server +Then: the 'barney.net' server creates a new comment #420 +And: the 'barney.net' server posts a request to the 'fred.org' server confirming that the request initiated by user 'fred@fred.org' to create a ticket comment was honored, and is accessible at the URL: 'barney.net/barney/barney-made-this/issues/42#comment-420' +And: the 'barney.net' server posts a request to the 'pebbles.me' server indicating that user 'fred@fred.org' has posted a comment to 'barney.net/barney/barney-made-this/issues/42' +When: the 'fred.org' server receives the comment acknowledgment from the 'barney.net' server +Then: the 'fred.org' server posts a request to the 'pebbles.me' server indicating that user 'fred@fred.org' has posted a comment to 'fred.org/barney-made-this/42' +When: pebbles logs into 'pebbles.me' +Then: pebbles sees a link to or contents of the comment by user 'fred@fred.org' on 'fred.org/barney-made-this/42' +And: pebbles sees a link to or contents of the comment by user 'fred@fred.org' on 'barney.net/barney/barney-made-this/issues/42' +And: fred's comments, when viewed on 'fred.org/barney-made-this/42', will be denoted as "verified" +And: if 'fred.org' has supplied a GPG key to 'barney.net' for user 'fred@fred.org', fred's comments, when viewed on 'barney.net/barney/barney-made-this/issues/42', will be denoted as "verified" +And: if 'fred.org' has supplied a GPG key to 'pebbles.me' for user 'fred@fred.org', fred's comments, when viewed on locally, will be verified locally ```