Skip to content

Prepare the v3.3.0 release - #762

Merged
anakinj merged 1 commit into
jwt:mainfrom
anakinj:clarify-error-hierarchy-upgrade-notes
Sep 11, 2026
Merged

Prepare the v3.3.0 release#762
anakinj merged 1 commit into
jwt:mainfrom
anakinj:clarify-error-hierarchy-upgrade-notes

Conversation

@anakinj

@anakinj anakinj commented Sep 11, 2026

Copy link
Copy Markdown
Member

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:

  1. The rescue is around JWT.encode, not JWT.decode.
  2. It names JWT::DecodeError, JWT::IncorrectAlgorithm, JWT::UnsupportedEcdsaCurve or ArgumentError.
  3. It is reachable at all, which takes a key or algorithm that cannot sign in the first place.

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 secp256k1 key used with ES256, which slips past its own bit-length guard. It is capped at jwt < 3.0 and 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 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 an intended consequence.

Also calls out the decode-side change from an escaping NoMethodError to a JWT::VerificationKeyError as catching more rather than less, so the compatibility claim stays honest.

Documentation only, no code changes.

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
anakinj force-pushed the clarify-error-hierarchy-upgrade-notes branch from 28d8f25 to 0825b1c Compare September 11, 2026 20:29
@anakinj anakinj changed the title Frame the error hierarchy change as backwards compatible Prepare the v3.3.0 release Sep 11, 2026
@anakinj
anakinj merged commit ccf2489 into jwt:main Sep 11, 2026
15 checks passed
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