[taler-docs] 02/02: redo diagram in dot

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

commit 160809d12e9a956ffb4cbef0e3cb8cbb72804114
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sat Apr 8 17:47:08 2023 +0200

    redo diagram in dot
---
 Makefile                                           |  4 +-
 .../037-wallet-transactions-lifecycle.rst          | 66 ++++++++++++++--------
 transaction-common-states.dot                      | 28 +++++++++
 3 files changed, 74 insertions(+), 24 deletions(-)

diff --git a/Makefile b/Makefile
index 6bb8992..cb844de 100644
--- a/Makefile
+++ b/Makefile
@@ -53,6 +53,8 @@ clean:
 
 arch-api.png: arch-api.dot
        dot -Tpng arch-api.dot > arch-api.png
+transaction-common-states.png: transaction-common-states.dot
+       dot -Tpng transaction-common-states.dot > transaction-common-states.png
 coin.png: coin.dot
        dot -Tpng coin.dot > coin.png
 deposit.png: deposit.dot
@@ -60,7 +62,7 @@ deposit.png: deposit.dot
 reserve.png: reserve.dot
        dot -Tpng reserve.dot > reserve.png
 
-diagrams: arch-api.png coin.png
+diagrams: arch-api.png coin.png deposit.png reserve.png 
transaction-common-states.png
 
 
 # The html-linked builder does not support caching, so we
diff --git a/design-documents/037-wallet-transactions-lifecycle.rst 
b/design-documents/037-wallet-transactions-lifecycle.rst
index 8a8df2e..64ec242 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -23,7 +23,7 @@ and aborting have transaction-specific sub-states, denoted by 
``state(substate)`
 
 ``initial``: The initial state is the result a user interaction. A transaction
 may have more than one initial state (if it is started in multiple ways) or 
none
-(if it's the result of another process)
+(if it's the result of another process).
 
 ``pending``: A pending transaction waits for some external event/service.
 The transaction stays pending until its change on the wallet's material balance
@@ -31,12 +31,13 @@ is finished. Any pending state can be suspended and resumed.
 
 There are some other distinctions for pending transactions:
 
-* long-polling vs exponential backoff: A pending transaction is either waiting
+* long-polling vs. exponential backoff: A pending transaction is either waiting
   on an external service by making a long-polling request or by repeating 
requests
   with exponential back-off.
 * ``lastError``: A pending transaction is either clean (i.e. the network 
interaction
   is literally active in transmission or the external service successfully
-  communicated that it is not ready yet) or has a ``lastError``, which is a 
``TalerErrorDetails``
+  communicated that it is not ready yet and this is perfectly normal)
+  or has a ``lastError``, which is a ``TalerErrorDetails``
   object with details about what happened during the last attempt to proceed
   with the transaction.
 
@@ -47,7 +48,7 @@ never has a ``lastError`` but is considered successful.
 complete the transaction, the wallet is taking active steps to abort it. The 
``lastError``
 indicates errors the wallet experienced while taking active steps to abort the 
transaction.
 
-``aborted``: Similar to a ``done`` transaction, but the transaction was 
successfully aborted
+``aborted``: Similar to ``done``, but the transaction was successfully aborted
 instead of successfully finished. It will have the information of when 
(timestamp) it was
 aborted and in which pending sub-state the abort action was initiated. Also, 
we can
 include more information information relevant to the transaction in 
`abortReason`
@@ -55,11 +56,11 @@ include more information information relevant to the 
transaction in `abortReason
 ``suspended``: Similar to a ``aborted`` transaction, but the transaction was 
could be
 resumed and may then still succeed.
 
-``failed``: Similar to ``done``, but the transaction could not even be aborted 
successfully.
+``failed``: Similar to ``done``, but the transaction could not even be aborted 
properly.
 
 ``deleted``: A ``deleted`` state is always a final state.  We only use this
 state for illustrative purposes. In the implementation, the data associated
-with the transaction would be deleted.
+with the transaction would be literally deleted.
 
 
 Common Transitions
@@ -67,12 +68,12 @@ Common Transitions
 
 Transitions are actions or other events.
 
-``[action:delete]``: Deleting a transaction (also called "forgetting" in the 
UI)
-completely deletes the transaction in the database.  Depending on the type of
+``[action:delete]``: Deleting a transaction
+completely deletes the transaction from the database.  Depending on the type of
 transaction, some of the other data *resulting* from the transaction might
 still survive deletion. For example, deleting a withdrawal transaction does not
 delete already successfully withdrawn coins. Deleting is only safe (no money 
lost)
-on initial and final state (failed, aborted, done)
+on initial and final states (failed, aborted, done).
 
 ``[action:retry]``: Retrying a transaction *(1.)* stops ongoing long-polling
 requests for the transaction *(2.)* resets the retry timeout *(3.)* re-runs the
@@ -84,35 +85,51 @@ states: ``pending(*)`` and ``aborting(*)``.
    Should we show the retry timeout in the UI somewhere?  Should we show it in 
dev mode?
 
    SEBASJM: Since the wallet will retry anyway, maybe is better if we replace 
the "retry"
-   button with a "try now" button and a side text "retrying in xxx seconds"
+   button with a "try now" button and a side text "retrying in xxx seconds".
+
+   CG: Instead of a side text, this *might* make a good mouse-over hint for
+   a "retry" (or "try now") button. I would not make this overly visible with
+   side-text as the information is not that important. The text should also be
+   "retrying next at XXX" using an absolute time XXX --- otherwise the UI would
+   be way too busy recomputing/updating all of these strings: Using an 
absolute time,
+   we only have to redraw anything once a retry actually happened. Given that
+   retries should basically never be > 24h (we can impose a hard cap), the 
absolute
+   time can just be in the format HH:MM:SS (without day).
 
 ``[action:abort]``: Aborting a transaction either directly stops processing 
for the
-transaction and puts it in an ``aborted`` state or starts the necessary steps 
to
+transaction and puts it in an ``aborted`` state, or starts the necessary steps 
to
 actively abort the transaction (e.g. to avoid losing money) and puts it in an
 ``aborting`` state.
 
-``[action:suspend]``: Suspends a pending transaction, stopping any associated 
network activities, but with a chance of trying
-again at a later time. This could be useful if a user needs to save battery 
power or bandwidth and an operation is expected
-to take longer (such as a backup, recovery or very large withdrawal operation).
+``[action:suspend]``: Suspends a pending transaction, stopping any associated
+network activities, but with a chance of trying again at a later time. This
+could be useful if a user needs to save battery power or bandwidth and an
+operation is expected to take longer (such as a backup, recovery or very large
+withdrawal operation).
 
-``[action:resume]``: Suspended transactions may be resumed, placing them back 
into a pending state.
+``[action:resume]``: Suspended transactions may be resumed, placing them back
+into a pending state.
 
-``[action:abort-force]``: Directly puts an ``aborting`` transaction into the 
``failed`` state.
+``[action:abort-force]``: Directly puts an ``aborting`` transaction into the
+``failed`` state.
 
 
-Whether aborting or resuming is possible depends on the transaction type, and 
usually only one
-of the two choices should be offered.
+Whether aborting or resuming are possible depends on the transaction type, and
+usually only one of the two choices should be offered.
 
 
-.. image:: ../transaction-common-states.svg
+.. image:: ../transaction-common-states.png
   :width: 400
 
-Boxed label means end state, where it is safe to delete the transaction record 
since no work is due.
 
-Blue arrows means mean user-triggered actions
+Boxed labels indicate an end state in which it is safe to delete the
+transaction record since no work is due.
+
+Blue arrows are used for user-triggered actions (via UI buttons).
+
 
 Common pending sub-states
----------------------------------
+-------------------------
 
 During the pending state the transaction can go through several sub-states 
before
 reaching a final state. Some of this sub-states are shared between different
@@ -627,7 +644,10 @@ The payment succeed but if auto-refund-check is active it 
will be checking for r
 Alternatives
 ============
 
-* each transaction could be treated completely separately
+* Each transaction could be treated completely separately; however, uniform
+  terminology for actions (and thus button labels) is likely more helpful for
+  the user experience.
+
 
 Drawbacks
 =========
diff --git a/transaction-common-states.dot b/transaction-common-states.dot
new file mode 100644
index 0000000..890cc23
--- /dev/null
+++ b/transaction-common-states.dot
@@ -0,0 +1,28 @@
+digraph G {
+
+  initial[label="", shape="circle"];
+  pending[label="pending"];
+  done[label="done", shape="box"];
+  aborted[label="aborted", shape="box"];
+  aborting[label="aborting"];
+  failed[label="failed", shape="box"];
+  suspended[label="suspended"];
+
+  subgraph {
+    rank = same; pending;suspended;
+  }
+
+  subgraph {
+    rank = same; done; aborted; failed;
+  }
+
+  initial->pending;
+  pending->suspended [color="blue",label="suspend"];
+  suspended->pending [color="blue",label="resume"];
+  pending->done [color="green",label="success"];
+  pending->failed [color="red",label="error"];
+  pending->aborting [color="blue",label="abort"];
+  pending->aborted [color="blue",label="abort"];
+  aborting->aborted [color="green",label="success"];
+  aborting->failed [color="red",label="error"];
+}

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.