Reading Semantic Versioning and Changelogs

2.3.1 → 2.4.0 is a minor version bump — new features, backward-compatible:

Semantic Versioning (SemVer) format: MAJOR.MINOR.PATCH

• MAJOR → breaking changes. Existing code may stop working. Consumers must review and update their integration.
• MINOR → new features added in a backward-compatible way. Existing code should continue to work.
• PATCH → bug fixes only. No new features, no breaking changes.

In 2.4.0, the MINOR number went from 3 to 4, meaning new functionality was added. The changelog confirms this: the Added section has new features (webhooks, --dry-run, PostgreSQL 16 support).

Note the nuance: While 2.4.0 is "backward-compatible" by SemVer rules, the Changed section shows client.connect() now returns a Promise (was synchronous). This is a behavioral change that could break code — careful library authors would note this as a migration concern even within a minor release.

Deprecated = still works but scheduled for removal; Removed = gone in this version:

This distinction is critical for developers maintaining long-lived integrations:

• Deprecated (in v2.4.0): client.connectSync() and config.legacyMode still work in 2.4.0, but the changelog warns they will be removed in v3.0.0. You have time to migrate.
• Removed (in v2.3.0): client.legacyConnect() is completely gone — if your code calls it, it will throw an error after upgrading to 2.3.0.

Keep a Changelog section lifecycle:

1. Feature is Added in v1.x.0
2. Feature is Deprecated in v2.x.0 with a migration path provided
3. Feature is Removed in v3.0.0 (major version bump signals breaking change)

The notice in v2.3.0 confirms this: "removed as announced in v2.1.0 deprecation notice" — meaning it was deprecated first, then removed a major version later.

Patch releases fix bugs only — and v2.3.1 confirms this perfectly:

The v2.3.1 section contains only a ### Fixed section with three bug fixes:

• A race condition when multiple clients connect simultaneously (#2041)
• An incorrect error message on connection timeout (#2055)
• A memory leak in event listener cleanup (#2061)

No new features, no changed behaviour, no deprecations — exactly what a patch release should contain.

Why patch releases matter for upgrade decisions:

• PATCH update (2.3.0 → 2.3.1): Almost always safe to apply immediately. Fixes bugs without changing the API surface.
• MINOR update (2.3.1 → 2.4.0): Read the Changed section carefully — new features are safe, but behavioural changes may require code updates.
• MAJOR update (2.x → 3.0.0): Always review breaking changes and test thoroughly before upgrading.

Issue references (#2041, #2055, #2061): The hash numbers link to GitHub/GitLab issues, providing full context about what was broken and how it was fixed — useful for verifying that the specific bug affecting your project is resolved.

Plan a migration to the async replacement before v3.0.0 is released:

The deprecation notice states: "will be removed in v3.0.0. Migrate to client.connect()."

The right approach:

1. Note the timeline: v3.0.0 is a future major release. You have time, but don't ignore this.
2. Understand the migration: connectSync() is synchronous; connect() returns a Promise. This likely requires adding await at call sites.
3. Plan and schedule: Add a task in your backlog to migrate before upgrading to v3.0.0.
4. Test after migrating: Switching from sync to async can introduce subtle ordering bugs.

Why deprecation warnings exist: They are a courtesy — maintainers giving consumers advance notice before a breaking change. Ignoring them until a major version is released often means scrambled last-minute migrations under pressure.

Option A is a common mistake: Deprecated features are eventually removed. Treating deprecation as permanent creates technical debt that grows more painful over time.

Breaking changes require consumers to review the migration guide and update integration code:

A breaking change means the library's public API has changed in a way that will cause existing code to break if you upgrade without making changes. In this changelog, the v2.4.0 entry has a hint of this: client.connect() now returns a Promise (was synchronous) — if your code called client.connect() and expected a synchronous result, it will now behave differently.

What to do when you see breaking changes:

1. Read the migration guide: Well-maintained projects publish upgrade guides (e.g., MIGRATING.md) listing every breaking change with before/after code examples.
2. Pin your version: Use exact version pinning ("my-lib": "2.3.1") until you are ready to migrate.
3. Test in a branch: Upgrade in an isolated branch, run your full test suite, and review any failures against the changelog.

SemVer contract: When a library follows SemVer, a MAJOR version bump (e.g., 2.x → 3.0.0) is the signal that breaking changes are present. Libraries that introduce breaking changes in minor or patch versions are violating SemVer — a red flag for reliability.