Skip to content

doc: a summary above the per-PR lines of each 2.x release - #1

Open
jappeace-sloth wants to merge 5 commits into
mainfrom
changelog-release-summaries
Open

jappeace-sloth wants to merge 5 commits into
mainfrom
changelog-release-summaries

Conversation

@jappeace-sloth

@jappeace-sloth jappeace-sloth commented Oct 6, 2026 •

Copy link
Copy Markdown
Owner

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:

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

jappeace-sloth and others added 2 commits October 6, 2026 20:34
…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>
@jappeace-sloth jappeace-sloth changed the title doc: a summary for each 2.x release doc: a short summary per release instead of the per-PR list Oct 6, 2026
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>
@jappeace-sloth jappeace-sloth changed the title doc: a short summary per release instead of the per-PR list doc: a summary above the per-PR lines of each 2.x release Oct 6, 2026
jappeace-sloth and others added 2 commits October 6, 2026 21:07
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant