Release Note

Semantic Versioning (SemVer) Release Notes Guideline

This document defines the standard steps and rules for writing Release Notes for the project, based on Semantic Versioning 2.0.0 (semver.org).

1. Core Rules of SemVer (X.Y.Z)

Every release version must follow the MAJOR.MINOR.PATCH format (e.g., 1.4.2). You must increment the respective element based on the scope of changes:

• MAJOR (X): Increment when you make incompatible API changes (Breaking changes). When MAJOR is incremented, MINOR and PATCH must be reset to 0 (e.g., 1.4.2 $\rightarrow$ 2.0.0).
• MINOR (Y): Increment when you add functionality in a backward-compatible manner. When MINOR is incremented, PATCH must be reset to 0 (e.g., 1.4.2 $\rightarrow$ 1.5.0).
• PATCH (Z): Increment when you make backward-compatible bug fixes without adding new features or breaking existing APIs (e.g., 1.4.2 $\rightarrow$ 1.4.3).

Note: Major version zero (0.x.x) is for initial development. Anything MAY change at any time. The public API should not be considered stable.

1.1. Additional Labels (Pre-release & Build Metadata)

SemVer allows appending labels to define the lifecycle of a release more precisely:

• Pre-release: Denoted by a hyphen - immediately following the PATCH version. These versions have a lower precedence than the associated normal version and are used for drafts or testing phases.
  • Examples: 1.0.0-alpha, 1.0.0-beta.1, 1.0.0-rc.1 (Release Candidate).
  • Precedence: 1.0.0-alpha < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0.
• Build Metadata: Denoted by a plus sign + at the very end. Used to store commit hashes, build IDs, or timestamps. This metadata does not affect version precedence.
  • Examples: 1.0.0-beta.1+exp.sha.5114f85, 1.2.3+20260601.

2. Step-by-Step: Writing Release Notes

When preparing a new release, follow these steps:

Step 1: Categorization

List all merged tickets/PRs. Group them into clear categories (following Keep a Changelog standards):

• Added: For new features.
• Changed: For changes in existing functionality.
• Deprecated: For once-stable features removed in upcoming releases.
• Removed: For deprecated features removed in this release.
• Fixed: For any bug fixes.
• Security: To invite users to upgrade in case of vulnerabilities.

Step 2: Determine the Version

• If there are any breaking changes or removed APIs $\rightarrow$ Increment MAJOR.
• If there are no breaking changes, but new features (Added) or APIs are introduced $\rightarrow$ Increment MINOR.
• If the list only contains Fixed or Security updates $\rightarrow$ Increment PATCH.

Step 3: Draft the Release Note

Use Markdown. Always specify the [Version] - Release Date (YYYY-MM-DD). Write concise and clear descriptions targeting end-users or API integrators. Avoid blindly copy-pasting cryptic git commit messages.

3. Concrete Examples

Below are 3 scenarios for creating release notes based on project changes.

Example 1: Patch Release (Bug Fixes)

Current version is 1.2.3. The team just fixed a server crash caused by empty payloads and patched a token security vulnerability. $\rightarrow$ Decision: Only bug fixes and security patches, increment PATCH to 1.2.4.

## [1.2.4] - 2026-06-01

### Fixed
- **API Reliability:** Handled HTTP 500 crash when an empty body (`undefined`) is sent to the Feature Flag API. The system now correctly returns a 400 Bad Request.
- **Swagger UI:** Updated the DTO to correctly render the input field in Swagger UI, resolving the fake 400 error upon execution.

### Security
- **Auth Guard:** Patched a vulnerability that allowed bypassing authentication with old cookies when the header token was expired.

Example 2: Minor Release (New Features)

Current version is 1.2.4. The team just added a configuration sync system via Redis and an API to toggle On-chain mode. Existing APIs are unaffected. $\rightarrow$ Decision: Backward-compatible new features, increment MINOR to 1.3.0.

## [1.3.0] - 2026-06-15

### Added
- **Config Sync Service:** Implemented dual-storage (MongoDB + Redis) to synchronize system configuration in real-time without requiring server restarts.
- **Feature Flag API:** Added a new endpoint `PUT /api/v1/system/admin/feature-flag/onchain-mode` allowing Admins to toggle the system into On-chain mode.
- **Telemetry:** Agents now automatically emit metrics logs every 10 minutes.

### Changed
- **Logs Format:** Changed console log output format to JSON for easier extraction into the ELK stack (API responses remain unaffected).

Example 3: Major Release (Breaking Changes)

Current version is 1.3.0. The team decided to overhaul the authentication architecture from JWT to OAuth2, removed the old /auth/login endpoint, and changed the response wrapper of all APIs from { data: ... } to { payload: ... }. $\rightarrow$ Decision: Breaking changes that will disrupt existing integrated clients, increment MAJOR to 2.0.0.

## [2.0.0] - 2026-07-01

> **⚠️ WARNING:** This release contains breaking changes. Please review the Migration Guide before upgrading.

### Changed
- **[BREAKING] Standard Response:** All APIs now return the `{ payload: ... }` wrapper instead of `{ data: ... }`. Client SDKs must update their parsers.
- **[BREAKING] Authentication:** Migrated the core authentication mechanism to the OAuth2 standard.

### Removed
- **[BREAKING] Legacy Auth:** The endpoints `/api/v1/auth/login` and `/api/v1/auth/refresh` have been officially removed from the system.
- **Legacy Transactions API:** Removed the Off-chain v1 processing module, which was deprecated in version 1.1.0.

4. Best Practices: Leveraging Conventional Commits

To ensure accurate version bumping and enable automation (CI/CD), the team should adopt the Conventional Commits specification:

• Commits starting with fix: ... $\rightarrow$ Automatically resolve to a PATCH.
• Commits starting with feat: ... $\rightarrow$ Automatically resolve to a MINOR.
• Commits containing BREAKING CHANGE: in the footer, or an exclamation mark ! (e.g., feat!: ...) $\rightarrow$ Automatically resolve to a MAJOR.

By doing so, determining the version (Step 2 above) is no longer subjective and can be fully automated using tools (like Semantic-release or Standard-version).