CHANGELOG: Documentation of changes, formatting

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c277899558af9c905ad6ef5202bb38c08a6e72e0..ecabfffb7adccc305c87f3432014f44f9b75474e 100644 (file)
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,51 +4,54 @@ Version 0.8.0 - UNRELEASED
 Bugfixes
 --------
 
- * Complete overhaul of Z coordinate (stacking order) handling.
-    - Reworked Z lowering algorithm.
+ * Complete overhaul of Z coordinate (stacking order) handling, including
+   reworked Z lowering algorithm (`b` key function).  Changes and
+   consequences include:
+    - On page load, use player's view of the Z coordinate for sort order (Z
+      display order) of occulted pieces, not actual Z (!)  resulting in
+      incoherent client state and arbitrary behaviours eg:
+    - Now we no longer ever raise a piece when user asks to lower (!!)
     - Occulters (hands and decks) more uniformly try to be low down.
-    - e.g. you will no longer accidentally put a card under your hand.
-    - Do not re-raise things during drag if the user explicitly
-      lowered them with `l`.
-    - When the user asks to raise but nothing can be raised, log
-      a message.
-    - Fix a Rust panicn in Z coordinate handling which might occur in
-      some attempts to lower pieces.
-    - Fix ordering of lowered pieces.
-    - Now we no longer ever raise a piece when you ask to lower it (!)
-    - On page load, use player's view of the Z coordinate for sort
-      order (Z display order) of occulted pieces, not actual Z (!!)
-
- * Overhaul of handling of errors detected when processing client API
-   requests:
-     - It should no longer be possible for the user to cause JS
-       exceptions or other lossage merely by asking to do things which
-       it happens that the server (unbeknownst to user or client
-       script.ts) won't permit.  Report these errors in the
-       user-facing client log window, instead.
-     - New discussion of inapplicable-api-op etc. error handling in
-       `PROTOCOL.md`, and implementation of the new scheme.
-
- * Fix JS exception if you had selected multiple pieces which used the
-   same key for different purposes.  (Even transiently, for example by
-   selecting multiple hand repositories and claiming them all - you'd
-   briefly have `C` for claim for some, and `C` for unclaim for
-   others.)
+    - e.g. user will no longer accidentally put card under their hand (!!)
+    - Do not derange relative ordering of multiple lowered pieces.
+    - Fix a Rust panic in Z coordinate handling which might occur in some
+      attempts to lower pieces.
+    - When the user asks to raise but nothing can be raised, log a message.
+
+ * Substantial overhaul of error handling for problems detected when
+   processing client API requests:
+    - It should no longer be possible for the user to cause JS exceptions or
+      other lossage merely by asking to do things which it happens that the
+      server (unbeknownst to user or client script.ts) won't permit.  Report
+      these errors in the user-facing client log window, instead.
+    - New discussion of inapplicable-api-op etc. error handling in
+      `PROTOCOL.md`, and implementation of the new scheme.
+    - Principled client decisions about what to show the user.
+
+ * Do not re-raise things during drag if the user explicitly lowered
+   them with `l`.
+
+ * Fix JS exception if user selected multiple pieces which used the same key
+   for different purposes.  (Even transiently, for example by selecting
+   multiple hand repositories and claiming them all - you'd briefly have `C`
+   for claim for some, and `C` for unclaim for others.)
 
 New features
 ------------
 
- * Player hands now show the count of contained pieces.
-
  * New general `t` keystroke to bring a piece to the top of the
    stackingorder.
 
- * New loosely synchroninised approach to "regrab", to enable a player
+ * Player hands now show the count of contained pieces.
+
+ * New loosely synchronised approach to "regrab", to enable a player
    to release a piece (eg, a card they have just drawn) and
    immediately, asynchronously, regrab it, while the server is sending
-   an update (eg resulting from an occultation status change).  I.e.,
-   you can now draw a card into your hand in Mao and immediately
-   regrab it,
+   an update (eg resulting from an occultation status change).  I.e.:
+     - You can now draw a card into your hand in Mao and immediately regrasp
+       it, planning to decide whether to play it - and you can do the regrasp
+       without waiting for the server to show you the card.  Your regrasp and
+       the server update run concurrently.
 
 Other user-facing changes
 -------------------------
@@ -56,7 +59,7 @@ Other user-facing changes
  * `vatikan` game spec: Make the two hands at the bottom bigger.
  * Deck card count uses a monospaced font.
 
-Internal and development changes
+Internal and development/test changes
 --------------------------------
 
  * Demo game: Add a label to the test hand.
@@ -78,7 +81,7 @@ Internal and development changes
  * Add more tests of zcoord module.
  * Tidy up some leftover comments etc.
  * Webdriver tests: check that there were no JS exceptions.
- * Improved debug output.
+ * Improved debug output in various places (when enabled or in tests).
  * Testing of inapplicable-api-op error handling.
  * Typo and formatting fixes in `PROTOCOL.md`.
  * Abolish the incoherent `OnlineError` error type and replace it