Feature Release with Deprecation Notices

Feature Release with Deprecations

Minor releases (e.g., v1.3.0) add new features while maintaining backward compatibility. When a minor release deprecates existing functionality, the release notes must clearly communicate both the exciting new features and the deprecation timeline.

Structure

## [1.3.0] - 2026-02-28

This release introduces the new Query Builder API and marks the
legacy `rawQuery()` function for removal in v2.0.

### Added
- New `QueryBuilder` class with fluent API (#312)
- Support for subqueries in WHERE clauses (#315)
- `explain()` method for query analysis (#318)
- Batch insert with automatic chunking (#320)

### Deprecated
- `rawQuery()` function — use `QueryBuilder.raw()` instead.
  Will be removed in v2.0.0. See migration guide. (#321)
- `Connection.execute()` positional params — use named
  parameters instead. Will be removed in v2.0.0. (#322)
- `legacyMode` config option — no longer needed with the
  new connection pooling. Will be removed in v2.0.0. (#323)

### Changed
- Connection pool now uses adaptive sizing by default (#316)
- Query logging format updated to include timing (#317)

### Fixed
- Fix connection leak when transaction fails (#310)
- Correct NULL handling in composite primary keys (#311)

Deprecation Notice Best Practices

Each deprecated item should include:

1. What is deprecated (function name, config option, behavior)
2. Replacement — what to use instead
3. Timeline — when it will be removed (specific version)
4. Migration path — link to guide or inline instructions
5. Runtime warning — confirm that the code emits deprecation warnings

Deprecation Timeline

v1.3.0 — Deprecated with warnings (current)
v1.4.0 — Warnings become errors in strict mode
v2.0.0 — Removed entirely

This gives users two minor releases to migrate, which is a common and reasonable timeline.