Docs: point everything at ML-KEM and write a migration guide #15

Activity

1. Zikithezikit

   added this to the 2.0.0 milestone on Oct 29, 2026
2. Zikithezikit

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   on Oct 29, 2026
3. Zikithezikit

   added a parent issue on Oct 29, 2026

   • [2.0] Add ML-KEM (FIPS 203) support while keeping legacy Kyber API with deprecation #3
4. Zikithezikit

   marked this as blocked by 2 issues on Oct 29, 2026

   • Python classes ML_KEM_512, ML_KEM_768, ML_KEM_1024 #13
   • Deprecation warning for the Kyber classes #14
5. Zikithezikit commented on Oct 30, 2026

   

   Zikithezikit

   on Oct 30, 2026

   OwnerAuthor

   More actions

   Handoff for whoever picks this up. #13 and #14 are merged into dev-v2.

   Scope: docs and version only. No change to Rust, to python/pykyber/ behavior, or to any test except where an example must change.

   Facts to use, all already in the code:

   • The migration page path must be exactly docs/migration.md. The KyberDeprecationWarning message (python/pykyber/_deprecation.py) already links https://github.com/Zikithezikit/pykyber/blob/main/docs/migration.md. The page must say that Kyber (round 3) and ML-KEM are not interoperable, both sides must switch, switching changes the shared secret, key and ciphertext sizes are identical so bytes cannot tell the two apart, and the ML-KEM seed is 64 bytes d || z (exposed as .seed only for seeded keypairs, and secret). ML-KEM methods refuse Kyber* objects with AlgorithmMismatchError. Mention that the warning is a DeprecationWarning, hidden by default unless raised from main, and how to show it (-W default::DeprecationWarning).
   • README quick start, docs/api.md and docs/index.md switch to ML_KEM_768 (NIST's default, FIPS 203 section 8). Run every example you write against a fresh maturin develop build.
   • Done when: no example in the repo uses Kyber except the migration page. Kyber stays documented as deprecated; do not remove or rename anything. Tests, vector generators and the benchmark are not examples; leave them alone unless a README or docs snippet is copied from them.
   • Version bump to 2.0.0 in BOTH Cargo.toml and pyproject.toml (plus the docs link in pyproject.toml). Cargo.lock will change; commit it. CHANGELOG: turn the Unreleased lines into a 2.0.0 entry.
   • Do not tag or publish. The maintainer does the dev-v2 -> main merge and the release; PLAN-2.0 section 5 lists what remains.
   • Keep README claims true: do not claim a security audit or constant-time guarantee that WP-8/9 have not produced.

   Rules: follow AGENTS.md (one PR against dev-v2, small commits that each pass scripts/check.sh, fixups instead of "fix review" commits, ASCII-checked PR text posted through the REST API). The docs link in the warning points at main, which will not have the file until the final merge; that is expected.
6. Zikithezikit

   closed this as completedon Oct 30, 2026
7. Zikithezikit commented on Oct 30, 2026

   

   Zikithezikit

   on Oct 30, 2026

   OwnerAuthor

   More actions

   Done in #39 (rebase-merged into dev-v2): README quick start, docs/api.md and docs/index.md use ML_KEM_768, the Kyber classes are documented as deprecated, docs/migration.md is in, and the version is 2.0.0 in Cargo.toml and pyproject.toml with the CHANGELOG entry. Nothing is tagged or published.