docs: rewrite about-checksums.md to STE rules - #2024
Conversation
gnodet
left a comment
gnodet
left a comment
There was a problem hiding this comment.
Nice STE rewrite — shorter sentences and active voice improve readability, and all hyperlinks are preserved this time (good!). A couple of accuracy items and some minor polish suggestions below.
This review was generated by an AI agent (Claude Code) and may contain inaccuracies. Please verify all suggestions before applying.
On behalf of gnodet
| proliferation of non-standard checksums. | ||
|
|
||
| ## Implemented Checksum Algorithms | ||
| The user configuration enables POMs to specify arbitrary checksum algorithms, |
There was a problem hiding this comment.
The original was deliberately generic ("one can set them via configuration"). The rewrite introduces "POMs" as the mechanism, but the project's own expected-checksums.md docs show checksum algorithms are configured via system properties (aether.layout.maven2.checksumAlgorithms) and -D flags, not POMs.
| The user configuration enables POMs to specify arbitrary checksum algorithms, | |
| Configuration allows users to specify arbitrary checksum algorithms, | |
| even if they are not part of the standard Maven process. |
|
|
||
| In the past, Maven Resolver used `java.security.MessageDigest` to calculate checksums. | ||
| The Java Cryptography Architecture provides secure one-way hashes. | ||
| Maven Resolver used these secure hashes to verify transport integrity. |
There was a problem hiding this comment.
The original's "(mis)used" was intentional editorial commentary — it acknowledged that applying cryptographic hash functions as transport checksums was a design shortcut, which motivates the SPI section that follows. Dropping it entirely loses that context. Consider preserving the nuance, e.g.:
Maven Resolver repurposed these secure hashes as checksums for transport integrity validation.
| This fact is true for the SHA-1 algorithm and the MD5 algorithm. | ||
| Industry still uses both algorithms today to verify transport integrity and to detect errors. | ||
|
|
||
| To prove that artifacts have not been tampered with, you need signatures such as |
There was a problem hiding this comment.
Minor: "prove" is stronger than the original "trust." GPG signatures provide cryptographic assurance from a trusted signer — they establish trust, not mathematical proof. The original word was more precise.
| To prove that artifacts have not been tampered with, you need signatures such as | |
| To trust that artifacts have not been tampered with, you need signatures such as |
Co-authored-by: Guillaume Nodet <gnodet@gmail.com>
gnodet
left a comment
gnodet
left a comment
There was a problem hiding this comment.
Thanks for fixing the grammar (comma + antecedent)! The main remaining item is the "POMs" reference on line 38 — checksum algorithms in Maven Resolver are configured via system properties (e.g. aether.checksums.algorithms), not POMs. The original was generic ("one can set them via configuration") for good reason. The previous review's suggestion block for this line is still applicable.
The other items ("(mis)used" context, "prove" vs. "trust") are editorial — your call whether to adjust.
This review was generated by an AI agent (Claude Code) and may contain inaccuracies. Please verify all suggestions before applying.
On behalf of gnodet
gnodet
left a comment
gnodet
left a comment
There was a problem hiding this comment.
The "POMs" reference is correctly replaced with "System properties" — factually accurate now. Grammar fix and this fix together address the substantive items. LGTM!
This review was generated by an AI agent (Claude Code) and may contain inaccuracies. Please verify all suggestions before applying.
On behalf of gnodet
* docs: rewrite api-compatibility.md to STE rules * docs: clarify clients vs extensions terminology Co-authored-by: Guillaume Nodet <gnodet@gmail.com> * Update src/site/markdown/api-compatibility.md Co-authored-by: Guillaume Nodet <gnodet@gmail.com> --------- Co-authored-by: Guillaume Nodet <gnodet@gmail.com>
2 participants
No description provided.