📋 Reading: CHANGELOG.md

SemVer and breaking changes — a critical reading skill for dependency management

Semantic Versioning (SemVer) uses the format MAJOR.MINOR.PATCH, with each component carrying a specific meaning:

• PATCH (e.g. 2.9.0 → 2.9.1): Bug fixes that do not change the public API. Safe to upgrade without code changes.
• MINOR (e.g. 2.8.0 → 2.9.0): New features added in a backward-compatible way. Existing code continues to work unchanged.
• MAJOR (e.g. 2.9.1 → 3.0.0): Breaking changes — the public API has changed in ways that are NOT backward-compatible. Code using the previous version may need modification to work with the new version.

Why this matters when reading a CHANGELOG:

• Upgrading from 2.x to 3.x → read the "Breaking Changes" section carefully before upgrading in production
• Upgrading from 2.8.0 to 2.9.1 → generally safe, but still worth checking Fixed/Deprecated sections

The v3.0.0 breaking changes in this CHANGELOG:

1. LegacyConsumer removed → any code importing this class will fail at runtime
2. connect() now returns a Promise → synchronous code calling const conn = connect() will break; must be updated to const conn = await connect()

Reading the migration guide: The changelog references docs/migration-v3.md — this is the correct first step for any major version upgrade. Well-maintained libraries always provide a migration guide alongside breaking changes.

Key vocabulary: "backward-compatible" = old code still works. "Breaking change" = old code will not work without modification. "Deprecated" = still works now, will be removed in a future major version.

Deprecation notices: the early warning system for breaking changes

A deprecation notice is a library author's courtesy: "We're going to remove this in the future — here's your time window to migrate." The correct response is not panic or immediate action, but planned migration before the removal deadline.

The deprecation lifecycle:

1. v2.9.1: LegacyConsumer deprecated. Runtime warning emitted. Still works 100%.
2. v2.9.x / v2.x.x: The feature continues to work. Migration can happen gradually.
3. v3.0.0: LegacyConsumer removed. Code using it will throw a runtime error or fail to compile.

What "plan and schedule migration" means in practice:

• Open a tech debt ticket in your issue tracker: "Migrate from LegacyConsumer to StreamConsumer before v3.0.0"
• Read the migration guide (docs/migration-v3.md) to understand the effort
• Allocate engineering time before you need to upgrade to v3.0.0 for other reasons (e.g., security fixes)

Why option A ("do nothing") is wrong: Deprecated features are removed at the next MAJOR release. Ignoring the notice means you either:

• Stay on an old version indefinitely (missing security patches), or
• Face a forced, high-pressure migration during an incident or security upgrade

The runtime warning: Many libraries emit a console/log warning when deprecated APIs are called. Monitoring for these warnings in production or test logs is a professional practice — they're the library's way of actively reminding you to migrate.

"Introduced in X.Y.Z" — regression tracing in changelogs

When a bug fix says "introduced in 2.8.0", the library authors are telling you the regression origin: this is a bug that didn't exist before 2.8.0. Code that worked correctly on 2.7.x started failing when it was upgraded to 2.8.0 — not because the user's code changed, but because the library changed.

Why this detail is invaluable:

• For teams on 2.7.x: You are NOT affected by this bug. This information helps prioritise whether this fix is urgent for you.
• For teams on 2.8.0 or 2.8.x: You have been affected since you upgraded. If you've experienced mysterious concurrency issues, this is likely the cause.
• For root cause analysis: "The bug was introduced in 2.8.0" is the kind of information that lets teams use git bisect to identify the exact commit, understand the root cause, and verify the fix is complete.

Reading between the lines — "race condition under high concurrency": This phrasing is common in bug fix entries and carries specific meaning:

• Race condition: A class of concurrency bug where the behaviour depends on the timing of events (threads, async operations). By definition, it's non-deterministic — it may not reproduce consistently in testing.
• Under high concurrency: The bug may only manifest under load (many simultaneous connections). It could be invisible in development and staging environments but appear in production under real traffic.

Cross-referencing the issue tracker: The fixed entry references #2341 — the GitHub issue number. In a real project, following this link gives you the full reproduction steps, original reporter, and the specific conditions under which the bug manifests. This is essential reading before deciding whether to upgrade immediately.