Prepare the v3.3.0 release - #762
Merged
Merged
Conversation
The version was bumped to 3.3.0 in jwt#729, so what is left before tagging is the changelog and the upgrade notes. Date the v3.3.0 changelog entry and drop the "Your contribution here" placeholder from it, as is done when cutting a release. The rest is the UPGRADING entry for the error hierarchy revamp in jwt#722, which 3.3.0 is the release that carries. It described the new classes first and reached the one incompatibility last, under a heading opening with "This is the part that can break", which is a poor summary of a change that needs no action from almost anyone upgrading. It now opens with a "Backwards compatibility" section stating the outcome: the classes were inserted above the existing ones rather than replacing them, so the errors an application already rescues keep their names, their meanings and everything they caught. The exception is given as three conditions that must all hold, the last being that the rescue is reachable at all, which takes a key or algorithm that cannot sign in the first place. A "Why this is a minor release" section explains the version choice, since a page arguing a change is backwards compatible invites the question of why it is not a major one. No call that used to succeed now fails or the reverse, so what moved is which rescue clause matches on a path that was already failing. It asks for an issue if anyone finds otherwise, which would be a bug rather than intended. The decode-side change from an escaping NoMethodError to a JWT::VerificationKeyError is called out as catching more rather than less, so the compatibility claim stays honest.
anakinj
force-pushed
the
clarify-error-hierarchy-upgrade-notes
branch
from
September 11, 2026 20:29
28d8f25 to
0825b1c
Compare
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.
The version was bumped to 3.3.0 in #729, so what is left before tagging is the changelog and the upgrade notes.
Changelog
Dates the v3.3.0 entry and drops the "Your contribution here" placeholder. The entries themselves were already complete: everything merged since v3.2.0 that is not listed is spec-only or CI-only and ships nothing.
Upgrade notes for #722
3.3.0 is the release that carries the error hierarchy revamp, and the UPGRADING entry for it described the new classes first and reached the one incompatibility last, under a heading opening with "This is the part that can break". That is a poor summary of a change that needs no action from almost anyone upgrading.
It now opens with Backwards compatibility, stating the outcome first: the classes were inserted above the existing ones rather than replacing them, so every error class an application already rescues keeps its name, its meaning and everything it used to catch. The exception is then given as three conditions that must all hold:
JWT.encode, notJWT.decode.JWT::DecodeError,JWT::IncorrectAlgorithm,JWT::UnsupportedEcdsaCurveorArgumentError.The third condition earns its place. Searching public code for the affected shape turned up a single project matching the first two, and it still needed a specific odd key before the rescue was reached at all — a
secp256k1key used withES256, which slips past its own bit-length guard. It is capped atjwt < 3.0and so cannot reach this release regardless, but it shows that clearing the first two conditions is not the end of the check.A Why this is a minor release section explains the version choice, since a page arguing that a change is backwards compatible invites the question of why it is not a major one. Nothing here turns a call that used to succeed into one that fails or the reverse, so what moved is which
rescueclause matches on a path that was already failing. It asks for an issue if anyone finds otherwise, which would be a bug rather than an intended consequence.Also calls out the decode-side change from an escaping
NoMethodErrorto aJWT::VerificationKeyErroras catching more rather than less, so the compatibility claim stays honest.Documentation only, no code changes.