CHANGELOG.md

   1 Version 1.1.0 - 2022-05-26
   2 ==========================
   3
   4 Bundle format
   5 -------------
   6
   7 Introduced bundle format versions, and bundle format version `2`.
   8 Bundle format version `1` is still supported.  There are significant
   9 changes and improvements in version `2`, available by writing
  10 `format=2`.  See "Bundle compatibility" in the documentation.
  11
  12  * Handling of piece size and angle specification overhauled.
  13  * New and better template substitution syntax.
  14  * Fixed piece angle specification in game specs.
  15
  16 Breaking change to otterlib CLI program
  17 ---------------------------------------
  18
  19  * otterlib (the library preview utility, not normally needed for bundle
  20    development) now needs to know the nwtemplates directory (so it can
  21    properly process etc. magic library items).
  22
  23 New features
  24 ------------
  25
  26  * Dice, via the `Die` piece type.
  27  * Currency (money, and similar things), via the `Currency` piece type.
  28  * Shape libraries can provide canned "magic" items
  29    (which are then based on the library's own image(s).
  30  * `stack_pos` parameter for `PickupDeck` pieces, specifying where the
  31    "neat pickup deck" should appear, so it doesn't have to central.
  32  * otter CLI client: Allow uploading a directory directly as a
  33    bundle zipfile (helpful for bundle development).
  34  * Include piece description in some log messages.
  35
  36 Fixes and improvements
  37 ----------------------
  38
  39  * Do not randomly panic when trying to print truncated debug output
  40    for non-ASCII piece HTML.
  41  * Set default fonts for SVG processing: in bundle SVGs, at all (so
  42    that text is not elided); in builtin libraries, more widely
  43    (without effect on the existing pieces).
  44  * Notice errors during JS startup, and display them.
  45  * Correct sense of pin/unpin log message.
  46  * Shape library previews: fix (and improve) the HTML (from otterlib).
  47  * Fix a tiny rendering error in arrowheads.
  48  * Test suite: `childio`: work around a Linux kernel race bug: you can
  49    sometimes reap a child and then write to its pipe without EPIPE.
  50  * Build system: run miri with +nightly, so that tests work when stable
  51    Rust is the default.  Document that these tests require nightly.
  52  * Correct an error message about JSON serialisation.
  53  * Remove some direct stderr debug prints from production code.
  54  * Log message colourisation on a tty now leaves the logs more readable.
  55  * Some improvements to bundle/shapelib loading error messages.
  56
  57 Docs
  58 ----
  59
  60  * Dcouemnt the semver stability promises.
  61  * Publish the docs to an Otter-version-specific directory, so that
  62    old docs versions are retained.
  63  * Fix some formatting errors and typos.
  64  * Correct some leftover todos.
  65  * Clarify extra field syntax in shape library catalogue `files` entries.
  66
  67 Protocol and model enhancements
  68 -------------------------------
  69
  70  * `multigrab`: pieces that can capture the number of pieces the user
  71    says to grab, and instead handle the whole multigrab operation.
  72  * `fastsplit`: pieces that can be split and merged during play
  73    without having to rewrite the aux save file (containing SVG images).
  74  * Non-mixing OccultIlk, for pieces which always remain distinguishable.
  75  * Special rendering instructions, for pieces whose display involves
  76    bespoke code in the TypeScript.
  77  * OpOutcomeThunk system to allow piece implementations to be reinvoked
  78    with an ability to make much wider mutable borrows.
  79
  80 Build system, internal changes, etc.
  81 ------------------------------
  82
  83  * Update to Rust 2021.
  84  * Break out an additional `otter-support` crate (to try to
  85    improve incremental build times).
  86  * Use `ambassador` macro crate to help delegate trait impls.
  87  * When formatting the Rust docs, pass `--document-private-items`.
  88    (The Rust doc tree is for Otter developers.)
  89  * Rationalised and sanitised the item import (`use`) practices.
  90  * Refactoring in the test suite to support new tests.
  91  * Fake time facility for testing.
  92  * Concrete protocol: more Quiet PieceUpdateOps.
  93  * Work around inkscape extension fail-to-save bug (seen in recolour).
  94  * Reorganised and shuffled about `Outline` types.
  95  * Avoid saving various things to savefiles that aren't needed
  96    (mostly `None`s).
  97  * Add some internal documentation about `ModifyingPieces`.
  98  * Code motion to better organise shapelib.rs and utils.rs
  99  * Centralised some UI properties in ui.rs.
 100  * Made some type names more consistent (eg `GOccults`, `Catalogue`).
 101  * Renamed some PacketFrame types etc. from MgmtChannel.
 102  * Other minor improvements.
 103
 104
 105 Version 1.0.0 - 2022-04-02
 106 ==========================
 107
 108 Significant changes
 109 -------------------
 110
 111  * Compile on stable Rust.
 112  * Uses actix-web rather than Rocket (should be similar in overall
 113    functionality but there may well be behavioural changes).
 114  * Always listen on localhost:8000 by default regardless of `debug` config.
 115    But, support explicit configuration of listening addresses.
 116  * Do not sometimes leak (in game log) piece identity of face-down cards.
 117
 118 Minor improvements
 119 ------------------
 120
 121  * Add short crate-level docs with reference to website etc.
 122  * Fix inconsequential misacceptance of some odd-length hex byte strings.
 123  * Fix some almost-incosequential short write bugs (might manifest as races).
 124  * Typo fix in one error message.
 125
 126 Build system
 127 ------------
 128
 129  * Turn on integer overflow checks for release builds.
 130  * Don't override environment's SPHINXBUILD or NAILING_CARGO.
 131  * Update dependency versions.
 132  * Skip some unnecessaary miri runs of certain tests.
 133  * Support for controlling the Rust version via RUST_VERSION.
 134  * `make deploy` MUSL build is in release mode by default.
 135  * Document that build now requires 6G rather than 10G.
 136
 137 Internal improvements
 138 ---------------------
 139
 140  * Drop wee-alloc as allocator from WASM.
 141  * Many internal code style improvements prompted by rust-clippy.
 142  * Remove some unused internal bits and bobs.
 143  * Require layout parameter in session URL loads.
 144  * Miscellanous Other cleanups.
 145
 146
 147 Version 0.7.3 - 2021-07-25
 148 ==========================
 149
 150 Build system bugfixes
 151 ---------------------
 152
 153  * `cargo` publication in `make-release` uses better pre-clean
 154    approach.  (Removes some junk from caago packages.)
 155
 156 drop our own directory from cargo.nail
 157
 158 Version 0.7.2 - 2021-07-25
 159 ==========================
 160
 161 Bugfixes
 162 --------
 163
 164  * Complete overhaul of Z coordinate (stacking order) handling, including
 165    reworked Z lowering algorithm (`b` key function).  Changes and
 166    consequences include:
 167
 168     - On page load, use player's view of the Z coordinate for sort order (Z
 169       display order) of occulted pieces, not actual Z (!)  avoiding
 170       incoherent client state and arbitrary behaviours eg:
 171     - Now we no longer ever raise a piece when user asks to lower (!!)
 172     - Occulters (hands and decks) more uniformly try to be low down.
 173     - e.g. user will no longer accidentally put card under their hand (!!)
 174     - Do not derange relative ordering of multiple lowered pieces.
 175     - Fix a logic errors and panics in Z coordinate handling which
 176       might prevent some attmepts to lower (or, mayby, raise) pieces.
 177     - When the user asks to raise but nothing can be raised, log a message.
 178     - Automatically lower occulting pieces when they are enabled, and
 179       pieces which are being pinned (insofar as reasonable); this
 180       significantly reduces the probability of mysterious trouble
 181       lowering a piece ("would disturb a piece held by another player").
 182
 183  * Substantial overhaul of error handling for problems detected when
 184    processing client API requests:
 185
 186     - It should no longer be possible for the user to cause JS exceptions or
 187       other lossage merely by asking to do things which it happens that the
 188       server (unbeknownst to user or client script.ts) won't permit.  Report
 189       these errors in the user-facing client log window, instead.
 190     - New discussion of inapplicable-api-op etc. error handling in
 191       `PROTOCOL.md`, and implementation of the new scheme.
 192     - Principled client decisions about what to show the user - which
 193       things are errors, which things are to be rported as conflicts, and
 194       generally what to put in the user-facing message log.
 195
 196  * Do not re-raise things during drag if the user explicitly lowered
 197    them with `b` (since the user grasped them).
 198
 199  * Fix JS exception if user selected multiple pieces which used the same key
 200    for different purposes.  (Even transiently, for example by selecting
 201    multiple hand repositories and claiming them all - you'd briefly have `C`
 202    for claim for some, and `C` for unclaim for others, triggering the bug.)
 203
 204 New features
 205 ------------
 206
 207  * New general `t` keystroke to bring a piece to the top of the
 208    stacking order.
 209
 210  * Player hands now show the count of contained pieces.
 211
 212  * New loosely synchronised approach to "regrab", to enable a player
 213    to release a piece (eg, a card they have just drawn) and
 214    immediately, asynchronously, regrab it, while the server is sending
 215    an update (eg resulting from an occultation status change).  I.e.:
 216      - You can now draw a card into your hand in Mao and immediately regrasp
 217        it, planning to decide whether to play it - and you can do the regrasp
 218        without waiting for the server to show you the card.  Your regrasp and
 219        the server update run concurrently.
 220
 221 Other user-facing changes
 222 -------------------------
 223
 224  * `vatikan` game spec: Make the two hand repositoriess at the bottom bigger.
 225  * Deck card count uses a monospaced font.
 226  * Demo game: Add a label to the test hand.
 227
 228 Internal and development/test changes
 229 -------------------------------------
 230
 231 New tests (and new checks in existing tests):
 232
 233  * Test Z lowering algorithm with new test facility.
 234  * Test handling of UI actions which server decides (unpredictably
 235    from client POV) cannot be performed.
 236  * Add more tests of the zcoord module.
 237  * Webdriver tests: check that there were no JS exceptions.
 238  * Add in-browser testing of inapplicable-api-op error handling.
 239  * Test new regrab feature, and adjust tests to cope with regrab
 240    feature's somewhat different reporting of simultaneous-drag-attempts.
 241  * Tests do a consistency check of the Z coordinates vs the in-SVG
 242    subelement stacking order.
 243
 244 Testing, supporting changes:
 245
 246  * New jstest facility for running for-browser JS in a nodejs
 247    environment with some cheesy mockups.  (New `otter-nodejs-tests`
 248    crate; involves a separate invocation of `wasm-bindgen`.)
 249  * Webdriver tests: pass window size arguments to firefox so we
 250    get a window big enough for the provided game specs.  Involves
 251    wrapper script for `firefox`.  Also Xvfb server screen size.
 252
 253 Internal and protocol improvements:
 254
 255  * New "loose" update (api op) concept to support new regrab feature.
 256  * Fix a wdriver synch race which could lead to spurious tests failures.
 257  * Improve defensive programming in the zcoord module.
 258  * Abolish the incoherent `OnlineError` error type and replace it
 259    with `Inapplicable` and `Fatal`.
 260  * Abolish old incoherent and ununused `conflict_expected` in client JS.
 261  * Improved debug output in various places (when enabled or in tests).
 262  * Cleaned up a few flabby idioms in some tests.
 263  * Promote some debugging support to otter-base.
 264
 265 Internal docs improvements:
 266
 267  * Fix some bogus links in internal docs.
 268  * Add some more internal documentation to the zcoord module.
 269  * Tidy up some leftover comments etc.
 270  * Typo and formatting fixes in `PROTOCOL.md`.
 271  * Fixes to `cargo doc` build.
 272
 273 Build system and dependencies:
 274
 275  * Update many dependencies to new versions.
 276  * Tested build with Rust nightly-2021-07-15.
 277  * Dependencies on tera templating engine slightly rationalised.
 278  * Maekfile: avoid rebuilding the otter cli over and over again,
 279    by touching it when we rebuild it.
 280
 281
 282 Version 0.7.1 - 2021-06-09
 283 ==========================
 284
 285 Bugfixes
 286 --------
 287
 288  * `make shapelib` builds, and reports a URL for, the actual
 289    documentation for shape library layout and spec syntax, not to an
 290    obsolete location.
 291
 292 Installation and deployment changes
 293 -----------------------------------
 294
 295  * Better documentation of how to install just the command line
 296    game management client (eg for use via ssh).
 297
 298  * Update Rocket dependency in Cargo.lock to one which builds with
 299    recent Nightly Rust.
 300
 301  * Update usvg dependency in Cargo.toml to a version with revised
 302    less-insane command line parsing, and adjust all calls to it.
 303
 304  * Updated other dependencies.
 305
 306  * Work around a cargo bug which breaks the docs build:
 307     https://github.com/rust-lang/cargo/issues/9564
 308
 309 Installation and deployment changes
 310 -----------------------------------
 311
 312  * Improvements to release checklist and release script.  Notably,
 313    add a checklist item for checking the build on recent Nightly.
 314
 315
 316 Version 0.7.0 - 2021-06-08
 317 ==========================
 318
 319 New features
 320 ------------
 321
 322  * Game spec files can now be processed with Tera for templating.
 323
 324  * ssh-based access for `otter` cli, including appropriately-
 325    restricted access via authorized_keys in the server role account,
 326    and a mechanism for self-service public key management.
 327
 328  * `otter` cli can now read a preferences file
 329    (`~/.config/otter/prefs.toml` by default) to allow pre-configuring
 330    commonly-required command line options like `--game` and `--ssh`.
 331    See `otter --help` for documentation.
 332
 333  * Mao and Penultima slightly updated (and, those game specs now
 334    use the new templating feature).
 335
 336 Bugfixes
 337 --------
 338
 339  * UI: When multiple pieces are selected and are to be raised (whether
 340    by explicit request, or because of drag distance), their relative
 341    ordering is preserved.  So dragging a group of pieces no longer
 342    scrambles their z order.
 343
 344  * UI: When the SSE connection auto-reconnects, do not declare it an
 345    error and suggest to the user that reloading might help.  Instead,
 346    simply hope that it is going to be OK (since it generally is).  If
 347    the SSE connection declares failure (state 2), report a scarier
 348    message.
 349
 350  * Docs: Fixes to some documentation errors (including a fix
 351    contributed by Simon Tatham).
 352
 353  * CLI etc.: Improve a number of error messages; in particular,
 354    replace several "debug prints" of error messages with proper
 355    formatting, and print a better program kname.
 356
 357  * CLI: Much better handling of stdout write errors.
 358
 359 Installation and deployment changes
 360 -----------------------------------
 361
 362  * The `otter` command line utility is now in its own Rust package
 363    `otter-cli`.
 364
 365  * Better logging by server of events on command connections.
 366
 367 Internal and development changes
 368 --------------------------------
 369
 370  * make-release now polls crates.io's github view to work around
 371    cargo/crates.io bug https://github.com/rust-lang/cargo/issues/9507
 372    and has a release checklist in it.
 373
 374  * Some internal renamings for clarity, especially regarding
 375    Authorisation proof tokens.
 376
 377  * Reworked the types involved in management command channels, to
 378    use a different stacking of read/write adapters.  In particular,
 379    a new `childio` facility for handling conversations with a child
 380    process (in support of using `ssh` as a command conn transport).
 381
 382  * `otter` cli no longer uses println!.  Instead we have a special
 383    wrapper for stdout which handles the errors and buffering for us.
 384
 385  * `otter` cli subcommand dispatch made nicer and the program's code
 386    broken out into multiple files.
 387
 388  * Internal apitest case code restructured somewhat.
 389
 390
 391 Version 0.6.0 - 2021-05-23
 392 ==========================
 393
 394 New features
 395 ------------
 396
 397  * Support uploading bundles of game materials, so games can be played
 398    that are not playable with Otter's provided piece libraries.
 399
 400  * New `vatikan.game.toml`, suitable for many variants of
 401    Manipulation Rummy.
 402
 403  * New `private.table.toml` and `same-scope.table.toml` for
 404    less-public games.
 405
 406 Command line usage changes, etc.
 407 --------------------------------
 408
 409  * otter(1) now takes the game name using a `--game` (`-g`) global
 410    option rather than a per-subcommand positional argument.
 411
 412  * Library listing, piece identification, and so on, changed,
 413    including changes to `otter library-add` and `otter library-list`.
 414    Specifically, per-game libraries mean that `library-list` now
 415    needs the `--game` option.
 416
 417  * otter(1) and otterlib(!) now honour `OTTER_CLI_LOG`
 418    (in Rust env_logger format).
 419
 420  * otter(1) no longer acts on change_directory server config
 421    setting (but still resolves paths in config relative to that dir).
 422
 423  * Much better reporting of errors, especially from otter(1).
 424    Previously even straightforward errors would result in a controlled
 425    `panic`; now a prettier message is printed.
 426
 427  * Default table size is now 300,200 (like `penultima` and `mao`; was
 428    400,200).
 429
 430   * otter(1) can be used to issue adhoc management commands supplied
 431     on the command line in JSON or RON format.
 432
 433 Bugfixes
 434 --------
 435
 436  * Fix a serious bug with acl handling which might allow players who
 437    can access a game more access than intended.
 438
 439  * Occult ilks are properly sorted out during piece load and game
 440    save/load.  Previously a game with occulted pieces might not be
 441    reloadable.
 442
 443  * Test suite might previously fail with EBADF due to off-by-one error
 444    in fd cleanup routiine.
 445
 446 Documentation
 447 -------------
 448
 449  * Document uploadable bundle format.
 450
 451 n * Document game and piece spec format.
 452
 453  * Document shape library catalogue format (previously this was done
 454    with rustdoc annotations on Rust structs used with serde, which
 455    produced incomplete and very hard to understand information).
 456
 457  * De-emphasize docs for for amending the builtin shape libraries;
 458    suggest making bundles instead.
 459
 460  * Examples, of game specs, shape libs, buncdles.
 461
 462 Installation and deployment changes
 463 -----------------------------------
 464
 465  * usvg is now built shipped by the otter build system.
 466
 467  * server-config.toml can specify the path to `usvg`, `libexec`,
 468    etc.
 469
 470 Compatibility notes
 471 -------------------
 472
 473  * The otter(1) command line interface has changed and many common
 474    operations need to be specified differently.
 475
 476  * The management API protocol has completely changed.  Old otter(1)
 477    clients will not work.
 478
 479  * Savefiles from older versions of Otter are not loadable.
 480
 481 Internal and development changes
 482 --------------------------------
 483
 484  * Change CLI to server management wire protocol to binary-framed
 485    MessagePack (was newline-framed JSON).
 486
 487  * Update dependencies.
 488
 489  * Build system and test suite improvements and fixes.
 490
 491  * Move game spec parsing from client to server.
 492
 493  * Better error messages, especially from otter(1)
 494
 495  * Tests have better error reporting and output capturing.
 496
 497  * Various substantial refactorings to tests.
 498
 499  * Test the supplied game specs.
 500
 501  * Test game save/load.
 502
 503  * Use the sphinx feature sphinx.ext.autosectionlabel for xrefs.
 504
 505  * Server management channel now has an idle timout.  Should not be
 506    relevant with the supplied otter(1) client.
 507
 508  * Much internal refactoring, new macros etc., to support the other
 509    work.
 510
 511  * Reset game (game spec parsing and implemnetation) is now
 512    done in the server rather than the client.
 513
 514  * Improvements and bugfixes to `make-release` and `update-version`
 515    scripts.  Fix anomalous (but working) `Cargo.toml` version
 516    dependency syntax.
 517
 518 Version 0.5.1 - 2021-04-19
 519 ==========================
 520
 521 This was the first public release.
 522
 523 [comment]: # Local variables:
 524 [comment]: # mode: text
 525 [comment]: # End: