Release Notes

Use this template when writing release notes for any repository or product release.

Purpose and Audience

Release notes serve two audiences simultaneously:

Non-technical stakeholders (product owners, business users, operations teams) — need to understand what changed in terms of visible behavior, new capabilities, and anything that requires action on their part.
Technical engineers (developers, platform engineers, on-call staff) — need to understand dependency changes, schema migrations, performance characteristics, and infrastructure impact.

Structure your release notes so each audience can read their relevant section independently. The user-facing section comes first; the technical section follows.

Structure

Version and Date Header

## [x.y.z] — YYYY-MM-DD

Use Semantic Versioning: MAJOR.MINOR.PATCH.

MAJOR — breaking changes that require user or operator action.
MINOR — new features that are backwards-compatible.
PATCH — backwards-compatible bug fixes.

User-Facing Changes

This section is written for non-technical readers. Lead with what changed for the user, not how it was implemented.

Features

New capabilities introduced in this release.

Improvements

Enhancements to existing behavior — performance visible to the user, usability, reliability.

Bug Fixes

Defects corrected. State what was broken and what the correct behavior now is.

Breaking Changes

Changes that alter existing behavior, remove functionality, or require user or operator action. Every breaking change must include an explicit migration guide (see Migration Guides below).

Technical Changes

This section is written for engineers. Omit it from announcements targeted at non-technical audiences.

Dependency Updates

Libraries, runtimes, or frameworks that changed version. Note any CVE fixes.

Performance

Measurable improvements or regressions in latency, throughput, or resource consumption.

Infrastructure and Configuration

Changes to deployment topology, environment variables, feature flags, or infrastructure-as-code.

Refactoring and Internal Changes

Internal restructuring with no user-visible impact. Keep this section brief — it is informational, not actionable.

Deprecations

Capabilities that will be removed in a future release. State:

What is deprecated.
What the replacement is (if any).
The target release for removal.

Migration Guides

One subsection per breaking change or deprecation. Each guide must include:

What the old behavior was.
What the new behavior is.
Step-by-step instructions for updating.
A link to any supporting documentation or script.

Known Issues

Defects or limitations present in this release that have not yet been resolved. For each:

Describe the symptom.
State any workaround.
Link to the tracking issue.

Style Guidelines

Lead with impact, not implementation. Write “Adds support for bulk-importing items via CSV” not “Adds CsvImportService and BulkImportController.”
Use present tense. Write “Adds support for…” not “Added support for…”.
Be specific about scope. If a change only affects a particular component or workflow, say so.
Breaking changes require migration steps. Never list a breaking change without a corresponding migration guide.
Link to authoritative sources. Reference the PR, issue, or documentation page for each significant change. Use relative .md links for internal documentation pages.
Omit internal jargon from the user-facing section. Reserve class names, module paths, and SQL schema details for the technical section.

Example Skeleton

## [2.4.0] — 2026-04-01

### Features

- Adds support for bulk-importing items from a CSV file. See [Bulk Import Guide](../../how-to/bulk-import.md).

### Improvements

- Reduces average page load time on the inventory list from 3 s to under 800 ms.

### Bug Fixes

- Fixes an issue where deleting an item with a pending order silently failed instead of showing an error message (#782).

### Breaking Changes

- The `/api/items` endpoint no longer accepts `application/x-www-form-urlencoded` requests. Clients must send `application/json`. See [Migration: Items API v2](#migration-items-api-v2).

---

### Technical Changes

#### Dependency Updates

- Upgrades `spring-boot` from 3.2.1 to 3.3.0 (includes CVE-2024-22233 fix).
- Upgrades `postgresql` JDBC driver from 42.6.0 to 42.7.3.

#### Infrastructure and Configuration

- Adds required environment variable `IMPORT_BUCKET_NAME` for the bulk-import feature. Set to the S3 bucket name used for staging CSV uploads.

#### Refactoring and Internal Changes

- Extracts item validation logic into a shared `ItemValidator` module used by both the REST and import pathways.

---

### Deprecations

- `GET /api/items/legacy-search` is deprecated and will be removed in v3.0.0. Use `POST /api/items/search` instead.

---

### Migration Guides

#### Migration: Items API v2

**Old behavior:** `POST /api/items` accepted both `application/json` and `application/x-www-form-urlencoded` content types.

**New behavior:** Only `application/json` is accepted.

**Steps:**

1. Update the `Content-Type` header in all client requests to `application/json`.
2. Encode the request body as a JSON object rather than a form-encoded string.
3. Verify by checking for a `200 OK` response; a `415 Unsupported Media Type` response indicates the old content type is still in use.

---

### Known Issues

- Bulk-import jobs for files larger than 50 MB may time out under high load. Workaround: split the file into smaller batches. Tracked in #801.

Document	Relationship
`pull-request.md`	The PR description provides the raw change list; the release notes synthesize it for a broader audience
`decision-log.md`	Architectural decisions recorded during the release may warrant a note in the deprecations or technical changes section
`implementation-plan.md`	Task completions map to feature and bug-fix entries in the release notes