[taler-docs] branch master updated (a7dd26c -> 160809d)

[gnunet]

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

grothoff pushed a change to branch master
in repository docs.

    from a7dd26c  address /pay documentation for #6952
     new c68cb55  whitespace
     new 160809d  redo diagram in dot

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 Makefile                                           |   4 +-
 .../037-wallet-transactions-lifecycle.rst          | 104 ++++++++++++---------
 transaction-common-states.dot                      |  28 ++++++
 3 files changed, 93 insertions(+), 43 deletions(-)
 create mode 100644 transaction-common-states.dot

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 3cc807e..64ec242 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -21,9 +21,9 @@ Common States
 The following states apply to multiple different transactions.  Only pending
 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)
+``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).
 
 ``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,19 +48,19 @@ 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
-instead of successfully finished. It will have the information of when 
(timestamp) it was 
+``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` 
+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
@@ -83,47 +84,63 @@ 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"
-
-``[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 
-actively abort the transaction (e.g. to avoid losing money) and puts it in an 
+   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".
+
+   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
+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 
+reaching a final state. Some of this sub-states are shared between different
 transaction types:
 
 ``kyc-required``: The transaction can't proceed because the user needs to 
actively
-finish a KYC process. Part of a withdrawal process or peer-to-peer push 
credit. 
+finish a KYC process. Part of a withdrawal process or peer-to-peer push credit.
 
 ``aml-required``: The transaction can't proceed because the user needs to wait 
for
-the exchange operator to conclude an AML investigation by the staff at the 
exchange. 
-The user is not expected to take any action and should just wait for the 
investigation 
+the exchange operator to conclude an AML investigation by the staff at the 
exchange.
+The user is not expected to take any action and should just wait for the 
investigation
 to conclude. Part of a withdrawal process or peer-to-peer push credit.
 
 ``aml-frozen``: The staff at the exchange decided that the account needed to 
be frozen.
@@ -162,7 +179,7 @@ user. So special-casing this and testing this is IMO just 
not worth it.
   exchange.
 
   (??) is this needed? let say that the money is wired but the signal
-  never of the bank confirmation reached the wallet, what should happen? 
+  never of the bank confirmation reached the wallet, what should happen?
 
   * ``[poll-success] => pending(exchange-wait-reserve)``
   * ``[action:abort] => aborting(wallet-to-bank)``
@@ -205,7 +222,7 @@ user. So special-casing this and testing this is IMO just 
not worth it.
 * ``aborted(partially-withdrawn)``:
 
   In this state, the wallet should show how much money arrived into the wallet
-  and the rest of the money will be sent back to the originating bank account 
+  and the rest of the money will be sent back to the originating bank account
   after ``$closing_delay``.
 
 * ``done``
@@ -254,7 +271,7 @@ instructedAmount, effectiveAmount and the affectedAmount 
(partially effective am
   of transitioning the UI into a ``pending(repurchase-session-reset)``
   on a different transaction (which before was in ``done``).
 
-  (??) should not reset another transaction? 
+  (??) should not reset another transaction?
 
 * ``pending(proposed)``
 
@@ -284,7 +301,7 @@ Submit coin by coin (or in bulk groups) until payment is 
complete.
 
 * ``pending(refundable)``
 
-The payment succeed but if auto-refund-check is active it will be checking for 
refunds 
+The payment succeed but if auto-refund-check is active it will be checking for 
refunds
 
   * ``[auto-refund-timeout] => done``
 
@@ -334,7 +351,7 @@ A refund is a pseudo-transaction that is always associated 
with a merchant payme
 
   A failed refund can technically still transition to ``done``, because the 
wallet
   doesn't query some refund resource, but the purchase for refunds.  Thus, a 
previously
-  failed refund can suddenly transition to ``done``. 
+  failed refund can suddenly transition to ``done``.
 
   (??) separate transient error vs permanent error ?
 
@@ -409,7 +426,7 @@ Submit coin by coin (or in bulk groups) until deposit is 
completed.
 
   * ``[action:abort] => aborting(refund)``
   * ``[processed-success] => pending(track)``
-  * ``[processed-error] => aborting(refresh)`` 
+  * ``[processed-error] => aborting(refresh)``
 
 * ``pending(track)``
 
@@ -605,7 +622,7 @@ Wallet read the taler:// URI
 
 * ``pending(refundable)``
 
-The payment succeed but if auto-refund-check is active it will be checking for 
refunds 
+The payment succeed but if auto-refund-check is active it will be checking for 
refunds
 
   * ``[auto-refund-timeout] => done``
 
@@ -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.