Merge chore/release-0.9.0: migration guide and changelog cleanup

MIGRATING.md

@@ -0,0 +1,204 @@
+# Migrating
+
+## 0.8.0 → 0.9.0
+
+Twenty-one breaking changes. Nearly all of them are mechanical, and the
+compiler finds every one — nothing here changes behaviour silently.
+
+Three exceptions are worth reading before you start, because they change
+what an existing, compiling call *returns*: [unknown keys](#unknown-keys-are-reported-not-skipped),
+[predictions from a broken fit](#predictions-refuse-a-fit-they-cannot-answer-from),
+and [`Gaussian`'s operators](#gaussians-operators-are-gone).
+
+### Type parameters: `K` comes first
+
+`K` was last, so naming a history meant writing all four parameters to change
+the one that matters.
+
+```rust
+// before
+struct Ladder { history: History<i64, ConstantDrift, NullObserver, String> }
+struct Analysis<'h> { joint: Joint<'h, i64, ConstantDrift, NullObserver, &'static str> }
+
+// after
+struct Ladder { history: History<String> }
+struct Analysis<'h> { joint: Joint<'h> }
+```
+
+`History<K, T, D, O, R>` — key, time, drift, observer, rating rule — all
+defaulted. `HistoryBuilder` matches. There is a fifth parameter now (`R`), and
+you will never write it unless you use `default_rating_for`.
+
+`HistoryBuilder::<Untimed, _, _, String>::new()` becomes
+`HistoryBuilder::<String, Untimed>::new()`.
+
+### Predictions and joint queries take borrowed keys
+
+At `K = String` a string literal used to be impossible, and asking "who wins"
+cost four allocations of temporaries that all had to outlive the call.
+
+```rust
+// before, at K = String
+let ta = vec![a.to_string()];
+let ra: Vec<&String> = ta.iter().collect();
+let tb = vec![b.to_string()];
+let rb: Vec<&String> = tb.iter().collect();
+let teams: Vec<&[&String]> = vec![&ra, &rb];
+h.predict_win_probabilities(&teams)?;
+
+// after, at either key type
+h.predict_win_probabilities(&[&["alice"], &["bob"]])?;
+h.posterior_of(&[("alice", 1.0), ("bob", -1.0)])?;
+```
+
+At `K = &'static str` the old `&[&[&"a"]]` spelling still compiles — `Q` infers
+to `&str` and the two shapes coincide — so this is only a break for owned keys,
+where nothing compiled before.
+
+One cost: `predict_outcome(&[])` can no longer infer the key type. Annotate it,
+`let none: &[&[&str]] = &[];`. It bites only on that degenerate call.
+
+### Unknown keys are reported, not skipped
+
+**Read this one.** `log_evidence_for` used to `filter_map` unknown keys away,
+and an empty target list means *no restriction* downstream — so a list of
+entirely unknown keys returned the **whole-history** value. Measured:
+`log_evidence_for(["typo"])` returned exactly `log_evidence()`. On the one
+workload it is documented for, leave-one-out cross-validation, that is the
+un-held-out score.
+
+```rust
+let e = h.log_evidence_for(&["alice"])?;   // now Result
+let curve = h.learning_curve("alice");     // now Option
+```
+
+Note `&["alice"]`, not `&[&"alice"]`. These take borrowed keys like the
+prediction methods, so one spelling works at both key types.
+
+`learning_curve` and `filtered_learning_curve` return `Option`: `None` is "never
+heard of this key", `Some(vec![])` is "known, has not played". They used to be
+the same empty `Vec`.
+
+### Predictions refuse a fit they cannot answer from
+
+**Read this one too.** `converge` already refused to report a NaN fit, but
+nothing stopped a caller ignoring that error and predicting anyway. On a
+NaN-poisoned fit, `quality` returned `Ok(NaN)`, `predict_outcome().total()` was
+`NaN`, and `predict_win_probabilities` returned `Ok([0.0, 0.0])` — finite,
+plausible, and summing to zero against a doc promising one.
+
+Every `predict_*` path now returns `Err(NonFiniteSkill { .. })` there, and
+`Err(NoPerformanceVariance)` when `beta` is zero and every skill is a point
+mass. If you were ignoring `converge`'s error, you will start seeing these.
+
+### `Gaussian`'s operators are gone
+
+`Mul`, `Div`, `Add` and `Sub` were the EP product, cavity and variance-space
+convolutions, not arithmetic — `N(10,2) * N(4,3)` is `N(8.15, 1.66)`, and
+`a / c` could leave a negative precision whose `mu()` printed a confident `0`.
+
+They are `pub(crate)` inherent methods now. The public surface is `from_ms`,
+`from_mv`, `mu`, `sigma`, `variance`, `probability_below`, `probability_above`;
+`pi()` and `tau()` are internal. If you compared fits bit-for-bit on
+`(pi, tau)`, compare `(mu, variance)` — same information, still exact.
+
+### `Game` is the type you get
+
+`Game::ranked` returned an `OwnedGame`, so `let g: Game = Game::ranked(..)?` did
+not compile. Names swapped: `Game<T, D>` is public, `OwnedGame` is gone.
+
+`one_v_one` returns a `Game` rather than `(Gaussian, Gaussian)`, so it can be
+asked for `log_evidence()` like its siblings. For the old shape:
+
+```rust
+let post = Game::one_v_one(&a, &b, outcome, &opts)?.posteriors();
+let (a_post, b_post) = (post[0][0], post[1][0]);
+```
+
+### The joint is reached through `Joint`
+
+`History::posterior_of`, `posterior_of_at` and `expected_variance_reduction`
+were one-shot wrappers that re-factorised on every call. They are gone.
+
+```rust
+// before — pays for the factorisation twice
+let a = h.posterior_of(&terms)?;
+let b = h.posterior_of(&other)?;
+
+// after — pays once, and the borrow says so
+let joint = h.joint()?;
+let a = joint.posterior_of(&terms)?;
+let b = joint.posterior_of(&other)?;
+```
+
+### `InferenceError` is typed
+
+Six variants carried `&'static str` discriminators. Four enums replace them:
+`Parameter`, `Shape`, `OutcomeKind`, `CompetitorField`.
+
+```rust
+// before
+InferenceError::InvalidParameter { name: "drift_scale", value }
+InferenceError::MismatchedShape { kind: "ranks vs teams", .. }
+InferenceError::WrongOutcomeKind { context, expected, got }   // three &str
+
+// after
+InferenceError::InvalidParameter { parameter: Parameter::DriftScale, value }
+InferenceError::MismatchedShape { shape: Shape::OutcomeVsTeams, .. }
+InferenceError::WrongOutcomeKind { expected: OutcomeKind::Ranked, got }
+```
+
+Variants that split or merged:
+
+| before | after |
+|---|---|
+| `InvalidProbability { value }` | `InvalidParameter { parameter: Parameter::PDraw, value }` |
+| `JointUnavailable { reason }` | `EmptyHistory`, `JointRequiresScoredEvents`, `NotPositiveDefinite` |
+| `NonFiniteResult { context, step }` | `NonFiniteStep { context, step }` (convergence), `NonFiniteSkill { mu, sigma }` (prediction) |
+
+Every struct variant is `#[non_exhaustive]`, so `match` with a `..` and
+construct through the library.
+
+### Renames
+
+| before | after |
+|---|---|
+| `History::predict_quality` | `History::quality` |
+| `Outcome::scores_with_sigma` | `Outcome::scores_with_noise` |
+| `EventBuilder::scores_with_sigma` | `EventBuilder::scores_with_noise` |
+| `Outcome::Scored { sigma }` | `Outcome::Scored { score_sigma }` |
+| `OwnedGame` | `Game` |
+
+### Removed
+
+`History::intern`, `History::lookup` and `Index`. Nothing public ever accepted
+an `Index`, so there was nothing to do with one. `current_skill`, `rating` and
+`learning_curve` answer "does this history know this key" and all take a
+borrowed key.
+
+`TimeSlice`, `EventKind`, `KeyTable`, `CompetitorStore`, `Competitor` and `N01`
+are no longer exported. None was obtainable from a `History`.
+
+### Warnings, not errors
+
+`#[must_use]` now sits on the value types, so a dropped `EventBuilder` — an
+event you forgot to `.commit()`, previously a silent no-op — warns. So do
+dropped `Team`, `Member`, `Outcome` and `Joint` values. A `-D warnings` build
+will need updating.
+
+### Nothing to do, but worth knowing
+
+The joint factorisation is sparse with an AMD fill-reducing ordering:
+**745 ms → 1.11 ms** on a 1976-appearance fixture, and near-linear scaling where
+it was cubic. Results are unchanged; `feral-amd` is a new dependency (two
+crates, both `#![forbid(unsafe_code)]`).
+
+`HistoryBuilder::gamma(f64)` is shorthand for
+`.drift(ConstantDrift::new(gamma))`.
+
+`History::current_skills()` is the leaderboard query — every competitor's latest
+posterior in one pass, rather than a full smoothed curve each.
+
+`History::filtered_log_evidence_for(&["alice"])` completes the evidence matrix:
+forward-only *and* key-restricted, which is what per-competitor prequential
+scoring needs.

README.md

@@ -419,7 +419,8 @@ expensive than `quality()`. Scoring every pairing among `n` competitors is
 Every box on the old todo list is ticked, so it has been retired; open work
 lives in the issue tracker instead. The crate is in use and the API is still
 moving — breaking changes are batched into minor releases rather than dribbled
-out, and `CHANGELOG.md` records them.
+out. `CHANGELOG.md` lists them and [`MIGRATING.md`](MIGRATING.md) explains what
+to do about them.
 
 ## License
 

cliff.toml

@@ -58,6 +58,11 @@ commit_parsers = [
     { message = "^test", group = "Testing" },
     { message = "^chore\\(release\\): prepare for", skip = true },
     { message = "^chore", group = "Miscellaneous Tasks" },
+    { message = "^ci", group = "CI" },
+    # Every branch lands with `--no-ff`, so a release's merge commits outnumber
+    # its real ones and say nothing the merged commits do not. They were
+    # filling an "Other (unconventional)" section with 14 lines of noise.
+    { message = "^Merge ", skip = true },
     { body = ".*security", group = "Security" },
     { body = ".*", group = "Other (unconventional)" },
 ]

src/lib.rs

@@ -9,6 +9,10 @@
 //! This is a Rust port of
 //! [TrueSkillThroughTime.py](https://github.com/glandfried/TrueSkillThroughTime.py).
 //!
+//! Upgrading? `MIGRATING.md` in the repository root covers every breaking
+//! change, with the ones that alter what an existing call *returns* called out
+//! first.
+//!
 //! # Getting started
 //!
 //! Record results, converge, then read off skills: