Repository navigation
doc: a summary above the per-PR lines of each 2.x release - #1
Open
jappeace-sloth wants to merge 5 commits into
Open
jappeace-sloth wants to merge 5 commits into
jappeace-sloth wants to merge 5 commits into
Conversation
…mamoto#201 under 2.1.0 Since 45d6051 each change is one line and a link, which reads well; what a reader deciding whether to upgrade still lacks is what a release means for them. 2.1.4 to 2.1.7 open with that, 2.0.1 to 2.1.3 did not, and 2.0.0 said what breaks but not what it gives. Each now opens with a few plain sentences: what got faster, what got harder to attack, and what breaks, with the detail left to the lines below. Two corrections, each checked against the tags: * 2.0.1 listed kazu-yamamoto#197, kazu-yamamoto#198, kazu-yamamoto#199, kazu-yamamoto#200 and kazu-yamamoto#201, but `git log --merges crypton-v2.0.0..crypton-v2.0.1` holds only kazu-yamamoto#203: 2.0.1 was the maintenance release from the 2.0 branch. The five merged between crypton-v2.0.1 and crypton-v2.1.0, so they move to 2.1.0, and with them kazu-yamamoto#198, the ChaChaPoly1305 signature change. * 2.0.0 said no exported function changed its signature. Comparing the top-level signatures of every exposed module between crypton-v1.1.5 and crypton-v2.0.0 finds two that did, Crypto.MAC.Poly1305.initialize and auth (kazu-yamamoto#192); the paragraph now names them. The same comparison from crypton-v2.0.0 to crypton-v2.1.7 finds only the ChaChaPoly1305 pair. 2.0.0's breaking paragraph also gains the DH and ECDH peer validation (kazu-yamamoto#87, kazu-yamamoto#89) and the prime-order subgroup check (kazu-yamamoto#190), which refuse input that used to be accepted. 2.1.3's summary names the zero-length tag kazu-yamamoto#233 refuses, which is a breaking change in a patch release. Prompt: hmm, I guess we can make a pr or issue to crypton asking to clarify the changelog, the overview you gave me was a lot better then the barf I read on hackage. we don't need to explain side channel attacks but it's a lot more encouraging to know what's actually being done without all these details can you fork the repo and show me how that pr would look on a pr against jappeace-sloth/crypton? Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The one-line-per-PR lists run to several hundred lines for the 2.x series, and a reader deciding whether to upgrade has to piece together what a release means from titles such as "perf(gcm): read a short block where it lies". That list is already kept by git and GitHub, so each release now carries only its summary, with one link to the compare view for anyone who wants every change. Where a summary used to sit above a list it only partly covered (2.1.4, 2.1.5, 2.1.6, 2.1.3), it now says what the list said that matters to a user: the gcc 13 and AArch64 SHA-256 fixes in 2.1.4, the AArch64 GCM speed-up in 2.1.5, the PBKDF2 and scalarInv fixes in 2.1.6, and the fixes and speed-ups in 2.1.3. 2.0.0 gains ElGamal, Crypto.Debug and the C point multiplication, and getShared joins the CryptoError sentence. The bold "Breaking changes." and "Deprecated." labels become plain sentences. Unreleased is a summary of ML-KEM and ML-DSA. Sections before 2.0.0 are a few lines each already and are left alone. Every compare link was checked to resolve. Prompt: I think the real issue is that bullet list, we *just* want the summary in the changelog Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A summary on top for the reader deciding whether to upgrade, and the existing one line and link per pull request below it for the reader who wants to find a change, which is the format 45d6051 introduced. The compare links go again, since the PR lines already point at the detail. Against main the per-PR lines are untouched (234 links, same set), except that kazu-yamamoto#197 to kazu-yamamoto#201 move from 2.0.1 to 2.1.0, where the tags put them. Prompt: actually linking to the specific pr with a one line summary should be fine, I guess those can be in bullet lists Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A diff of the Hoogle files Hackage built for 1.1.5 and 2.0.0 shows CryptoError_PointSubgroupInvalid appended next to CryptoError_ParameterInvalid (both in Crypto/Error/Types.hs at crypton-v2.0.0, neither at crypton-v1.1.5); the summary named only the first. The same diff confirms the Poly1305 initialize and auth signature changes are the only changed or removed exports in 2.0.0. Prompt: can you fork the repo and show me how that pr would look on a pr against jappeace-sloth/crypton? Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Against crypton-v2.1.7, main also adds Crypto.KEM (the KEM class, and SharedSecret moved there from Crypto.ECC, which still re-exports it, with a new Show instance that redacts the secret) and appends CryptoError_PublicKeyStructureInvalid to CryptoError. The summary now names both, and says which existing code can notice: an exhaustive match on CryptoError, and an orphan Show SharedSecret instance. Prompt: can you fork the repo and show me how that pr would look on a pr against jappeace-sloth/crypton? Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
jappeace
pushed a commit
to jappeace/vibes
that referenced
this pull request
Oct 7, 2026
A changelog is not a commit history. The skill makes each version a short summary a reader can glance over (does it break me, what do I gain, do I have to act), followed by one line per pull request with a link; implementation detail stays in the PR and version control. Distilled from the crypton 2.x work of 6 Oct 2026: summarizing crypton's changelog for the mysql-haskell bound bump, and the changelog PR on jappeace-sloth/crypton#1. The verification section keeps the checks that each caught a real error there: listing what shipped per tag (five PRs were filed under the wrong release), an API diff before claiming "no API change" (two signatures had changed), reading PR bodies (a title undersold an authentication bypass) and reading the whole range (an earlier summary of ours counted 2 breaking changes where there were 26). scripts/hs-signature-diff.py diffs the exposed modules, export lists and exported top-level signatures of a Haskell package between two refs, ignoring doc comments and explicit foralls. Checked against the hand results: crypton 1.1.5..2.0.0 reports exactly Poly1305.initialize and auth, 2.0.0..2.1.7 exactly the ChaChaPoly1305 pair, 2.1.6..2.1.7 nothing; mysql-haskell (src/ layout) reports nothing; a fixture with a removed module, a removed primed export, a changed multi-line signature and a doc-only change reports the first three and not the fourth. Prompt: distill what we've done here in a changelog skill, a changelog is not a commit history, it should contain a summary per version of what was done easy to glance over by humans. If you want the details use the version control system actually linking to the specific pr with a one line summary should be fine, I guess those can be in bullet lists Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Hi! We maintain mysql-haskell and just widened its bound to crypton 2.1 for the stackage move (commercialhaskell/stackage#8128). Since 45d6051 the changelog is one line and a link per PR, which is a big improvement over the text on Hackage. What a reader deciding whether to upgrade still lacks is what a release means for them. 2.1.4 to 2.1.7 already open with a short paragraph saying so; this PR gives 2.0.1 to 2.1.3 one too, rounds out the existing ones, and keeps every per-PR line below them.
Each summary answers three questions: what breaks, what you gain (faster, harder to attack, new functions), and whether you have to act (for example "use 2.1.5 or later"). Where nothing breaks it says so, because that is the most reassuring line in the file.
Checking the summaries against the tags turned up two things in the current changelog:
git log --merges crypton-v2.0.0..crypton-v2.0.1contains only fix(cpu): stop reading Intel's SDBG bit as AMD's XOP kazu-yamamoto/crypton#203. That matters for fix(chachapoly1305): take a checked key, so that initializing cannot fail kazu-yamamoto/crypton#198, the ChaChaPoly1305 signature change, which currently reads as a breaking change in a patch release. The five lines move to 2.1.0; no other PR line changes (234 links before and after).Crypto.MAC.Poly1305.initializeandauthdid (fix(poly1305): take a checked key, so that initializing cannot fail kazu-yamamoto/crypton#192): they take a checkedKeynow. Diffing the Hoogle files Hackage built for 1.1.5 and 2.0.0, those two are the only changed or removed exports; the same diff showsCryptoError_PointSubgroupInvalidappended toCryptoErrornext toCryptoError_ParameterInvalid, which the summary now names too. From 2.0.0 to 2.1.7 the only changes are the ChaChaPoly1305 pair (Poly1305'sKeymoved to an internal module in 2.1.0 but kept its instances).The 2.0.0 summary also lists the DH/ECDH peer validation (kazu-yamamoto#87, kazu-yamamoto#89) and the subgroup check (kazu-yamamoto#190) among the refused inputs, and the bold "Breaking changes." / "Deprecated." labels become plain sentences.
Happy to reword anything to fit your style.
🤖 Generated with Claude Code