cargo publish would fail: no description, license, or repository — and the crate has no top-level docs #25

New Issue

2026-08-04T19:21:19Z

logaritmisk commented

2026-08-04 19:21:19 +00:00

The project has a full release pipeline — release.toml, cliff.toml, a maintained CHANGELOG.md, and three tagged releases (0.1.0 → 0.1.2) — but Cargo.toml is missing the metadata cargo publish requires.

Missing manifest keys

[package]
name = "trueskill-tt"
version = "0.1.2"
edition = "2024"

That is the entire [package] section. Absent:

description — cargo publish rejects the crate without it
license or license-file — likewise rejected; also, there is no LICENSE file in the repo at all, so the code currently carries no stated terms
repository, documentation, homepage — no links from crates.io/docs.rs back to the source
keywords, categories — undiscoverable in search
readme — README.md exists but isn't wired up
authors
rust-version — no declared MSRV, so there's nothing for CI to test against (#24) and no contract with consumers. edition = "2024" already implies Rust 1.85+, but that should be explicit
exclude — docs/, benches/baseline.txt, and temp/ would otherwise ship in the published tarball

No crate-level documentation

src/lib.rs opens directly with use std::{…} — there is no //! module doc. On docs.rs the landing page would be a bare symbol list with no explanation of what the crate is, what TrueSkill Through Time does, or how to start.

Every other module in the crate has a //! header, which makes the omission at the root conspicuous.

Also missing across the public API (from cargo clippy -- -W clippy::pedantic):

9 Result-returning public functions with no # Errors section
4 potentially-panicking public functions with no # Panics section — including predict_outcome and Outcome::winner, both of which do panic (#21, #20)
31 missing #[must_use] on pure accessors — notably Gaussian's arithmetic and posteriors()/log_evidence(), where discarding the result is always a bug
18 doc items missing backticks

None of these have doc examples either, so cargo test --doc currently verifies nothing.

Also

[profile.release] debug = true and the matching [profile.dev]/[profile.bench] entries: profile settings in a library are ignored by downstream consumers, so these only affect local builds. Harmless, but debug = true on release is worth a comment explaining it's there for cargo flamegraph (per the flame recipe in the Justfile) rather than looking like an oversight.

Acceptance

cargo publish --dry-run succeeds.
A LICENSE file exists and matches the license key.
src/lib.rs has a //! header with a runnable example.
rust-version is declared and verified by CI (#24).
Public Result/panicking functions document # Errors / # Panics.

The project has a full release pipeline — `release.toml`, `cliff.toml`, a maintained `CHANGELOG.md`, and three tagged releases (0.1.0 → 0.1.2) — but `Cargo.toml` is missing the metadata `cargo publish` requires. ## Missing manifest keys ```toml [package] name = "trueskill-tt" version = "0.1.2" edition = "2024" ``` That is the entire `[package]` section. Absent: - **`description`** — `cargo publish` rejects the crate without it - **`license`** or `license-file` — likewise rejected; also, there is no `LICENSE` file in the repo at all, so the code currently carries no stated terms - `repository`, `documentation`, `homepage` — no links from crates.io/docs.rs back to the source - `keywords`, `categories` — undiscoverable in search - `readme` — `README.md` exists but isn't wired up - `authors` - **`rust-version`** — no declared MSRV, so there's nothing for CI to test against (#24) and no contract with consumers. `edition = "2024"` already implies Rust 1.85+, but that should be explicit - `exclude` — `docs/`, `benches/baseline.txt`, and `temp/` would otherwise ship in the published tarball ## No crate-level documentation `src/lib.rs` opens directly with `use std::{…}` — there is no `//!` module doc. On docs.rs the landing page would be a bare symbol list with no explanation of what the crate is, what TrueSkill Through Time does, or how to start. Every other module in the crate has a `//!` header, which makes the omission at the root conspicuous. Also missing across the public API (from `cargo clippy -- -W clippy::pedantic`): - 9 `Result`-returning public functions with no `# Errors` section - 4 potentially-panicking public functions with no `# Panics` section — including `predict_outcome` and `Outcome::winner`, both of which do panic (#21, #20) - 31 missing `#[must_use]` on pure accessors — notably `Gaussian`'s arithmetic and `posteriors()`/`log_evidence()`, where discarding the result is always a bug - 18 doc items missing backticks None of these have doc examples either, so `cargo test --doc` currently verifies nothing. ## Also `[profile.release] debug = true` and the matching `[profile.dev]`/`[profile.bench]` entries: profile settings in a library are ignored by downstream consumers, so these only affect local builds. Harmless, but `debug = true` on release is worth a comment explaining it's there for `cargo flamegraph` (per the `flame` recipe in the `Justfile`) rather than looking like an oversight. ## Acceptance - `cargo publish --dry-run` succeeds. - A `LICENSE` file exists and matches the `license` key. - `src/lib.rs` has a `//!` header with a runnable example. - `rust-version` is declared and verified by CI (#24). - Public `Result`/panicking functions document `# Errors` / `# Panics`.

logaritmisk referenced this issue

2026-08-04 19:21:40 +00:00

Test suite has no coverage for degenerate inputs, release-mode behaviour, or non-finite results #26

logaritmisk commented

2026-08-04 20:12:32 +00:00

Partly done in 9506fed — staying open for the licence, which is yours to choose.

Added: description, repository, readme, keywords, categories, exclude, and rust-version = "1.85" (the edition-2024 floor, now verified by a CI job in #24).

src/lib.rs gained the missing //! header: what Through Time does differently from plain TrueSkill, three runnable examples, and the draw/p_draw interaction. cargo test --doc runs 3 tests where it previously had nothing to check.

cargo publish --dry-run now packages and verifies cleanly, stopping only on:

warning: manifest has no license or license-file

Remaining, and blocking publication:

Pick a licence. The Rust convention is license = "MIT OR Apache-2.0" with matching LICENSE-MIT / LICENSE-APACHE files. There is no LICENSE file in the repo at all today, so the source currently carries no stated terms. A TODO comment marks the spot in Cargo.toml.
# Errors / # Panics sections and #[must_use] across the public API are still missing — worth doing once the API changes in #20 and #21 settle, since both move which functions panic and which return Result.

Partly done in 9506fed — **staying open for the licence, which is yours to choose.** Added: `description`, `repository`, `readme`, `keywords`, `categories`, `exclude`, and `rust-version = "1.85"` (the edition-2024 floor, now verified by a CI job in #24). `src/lib.rs` gained the missing `//!` header: what Through Time does differently from plain TrueSkill, three runnable examples, and the draw/`p_draw` interaction. `cargo test --doc` runs 3 tests where it previously had nothing to check. `cargo publish --dry-run` now packages and verifies cleanly, stopping only on: ``` warning: manifest has no license or license-file ``` **Remaining, and blocking publication:** - Pick a licence. The Rust convention is `license = "MIT OR Apache-2.0"` with matching `LICENSE-MIT` / `LICENSE-APACHE` files. There is no `LICENSE` file in the repo at all today, so the source currently carries no stated terms. A TODO comment marks the spot in `Cargo.toml`. - `# Errors` / `# Panics` sections and `#[must_use]` across the public API are still missing — worth doing once the API changes in #20 and #21 settle, since both move which functions panic and which return `Result`.

logaritmisk commented

2026-08-27 15:43:51 +00:00

All five acceptance criteria met. trueskill-tt 0.2.0 is published to the kellnr registry.

Criterion	Status
`cargo publish --dry-run` succeeds	✅ — went further and actually published
LICENSE file exists and matches the `license` key	✅ `MIT OR Apache-2.0` + LICENSE-MIT + LICENSE-APACHE
`src/lib.rs` has a `//!` header with a runnable example	✅ 3 doctests, checked by `cargo test --doc`
`rust-version` declared and verified by CI	✅ `1.85`, per #24
Public `Result`/panicking functions document `# Errors` / `# Panics`	✅ `9b2c2b3`

The manifest keys all landed in 9506fed; the licence in b73cf01; the docs in 9b2c2b3. Clippy went from 56 warnings to zero across missing_errors_doc, missing_panics_doc, must_use_candidate and doc_markdown.

On the 13 hand-written sections: they name the actual variants rather than gesturing at "an error", which meant reading each error path. Game::ranked alone returns four distinct variants. record_draw can hit TieWithoutDrawProbability where record_winner provably cannot, since a two-team decisive outcome has nothing to tie. Documenting those as interchangeable would have been worse than leaving them undocumented, because a reader would trust it.

Two panics were already described in prose but not under a # Panics heading, so neither rustdoc nor clippy surfaced them — Outcome::winner and EventBuilder::weights. Both now carry it, and Outcome::winner gained a note that it ties every loser, so n >= 3 needs a positive p_draw. That is the easiest error in this crate to hit by accident.

Two notes for the record:

The licence turned out to be a hard blocker for the release workflow, not just crates.io. cargo publish does not check license for an alternative registry — verified by a clean dry run with none — but cargo release refuses outright with missing the following fields: license || license-file, and --no-verify does not bypass it.
The published tarball was going to be 48.1 MiB. All of it examples/atp.csv. It is read by relative path rather than include_str!, so excluding it still compiles and cargo package --verify still builds every target. Published size is 374 KiB / 88 KiB compressed. Your exclude list predated that fixture; nothing warns you, the only signal is the Packaged N files line.

The # Errors/# Panics deferral note above mentioned waiting on #20/#21 — that turned out unnecessary: predict_outcome and Outcome::winner are documented as panicking today, which is accurate regardless of whether those issues later convert them to Result.

All five acceptance criteria met. **trueskill-tt 0.2.0 is published** to the kellnr registry. | Criterion | Status | |---|---| | `cargo publish --dry-run` succeeds | ✅ — went further and actually published | | LICENSE file exists and matches the `license` key | ✅ `MIT OR Apache-2.0` + LICENSE-MIT + LICENSE-APACHE | | `src/lib.rs` has a `//!` header with a runnable example | ✅ 3 doctests, checked by `cargo test --doc` | | `rust-version` declared and verified by CI | ✅ `1.85`, per #24 | | Public `Result`/panicking functions document `# Errors` / `# Panics` | ✅ `9b2c2b3` | The manifest keys all landed in `9506fed`; the licence in `b73cf01`; the docs in `9b2c2b3`. Clippy went from 56 warnings to zero across `missing_errors_doc`, `missing_panics_doc`, `must_use_candidate` and `doc_markdown`. **On the 13 hand-written sections:** they name the actual variants rather than gesturing at "an error", which meant reading each error path. `Game::ranked` alone returns four distinct variants. `record_draw` can hit `TieWithoutDrawProbability` where `record_winner` provably cannot, since a two-team decisive outcome has nothing to tie. Documenting those as interchangeable would have been worse than leaving them undocumented, because a reader would trust it. **Two panics were already described in prose but not under a `# Panics` heading**, so neither rustdoc nor clippy surfaced them — `Outcome::winner` and `EventBuilder::weights`. Both now carry it, and `Outcome::winner` gained a note that it ties every loser, so `n >= 3` needs a positive `p_draw`. That is the easiest error in this crate to hit by accident. Two notes for the record: - **The licence turned out to be a hard blocker for the release workflow**, not just crates.io. `cargo publish` does not check `license` for an alternative registry — verified by a clean dry run with none — but `cargo release` refuses outright with `missing the following fields: license || license-file`, and `--no-verify` does not bypass it. - **The published tarball was going to be 48.1 MiB.** All of it `examples/atp.csv`. It is read by relative path rather than `include_str!`, so excluding it still compiles and `cargo package --verify` still builds every target. Published size is 374 KiB / 88 KiB compressed. Your `exclude` list predated that fixture; nothing warns you, the only signal is the `Packaged N files` line. The `# Errors`/`# Panics` deferral note above mentioned waiting on #20/#21 — that turned out unnecessary: `predict_outcome` and `Outcome::winner` are documented as panicking *today*, which is accurate regardless of whether those issues later convert them to `Result`.

logaritmisk closed this issue

2026-08-27 15:43:54 +00:00

logaritmisk referenced this issue from a commit

2026-08-27 16:41:51 +00:00

docs: complete the public API documentation contract

logaritmisk added the docs infra labels 2026-09-07 13:53:27 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: logaritmisk/trueskill-tt#25

cargo publish would fail: no description, license, or repository — and the crate has no top-level docs #25

Missing manifest keys

No crate-level documentation

Also

Acceptance

`cargo publish` would fail: no `description`, `license`, or `repository` — and the crate has no top-level docs #25