How to Write Effective Release Notes

Read the original article：How to Write Effective Release Notes

Requirement Description

Release notes must clearly communicate what has changed in a new version of an application or library. Developers, testers, and stakeholders should be able to quickly understand new features, improvements, bug fixes, breaking changes, and migration requirements.
This document provides guidelines and a standard structure for preparing effective, concise, and technically accurate release notes.

Background Knowledge

Before writing release notes, contributors should be familiar with:

• Versioning Practices Follow semantic versioning when possible (e.g., MAJOR.MINOR.PATCH). Example: 2.3.1 (bug fixes only), 3.0.0 (major breaking update).
• Change Types Release notes commonly include the following categories:
  • New Features
  • Improvements
  • Bug Fixes
  • Deprecations
  • Breaking Changes
  • Security Updates
  • Migration Notes (if applicable)
• Audience Release notes must serve:
  • Developers integrating your SDK/library
  • QA teams validating updates
  • Product managers or technical stakeholders
  • End users (optional, depending on distribution channel)
• Clarity Standards Huawei’s documentation style emphasizes:
  • Action-oriented descriptions
  • Consistent formatting
  • Compact, easy-to-scan bullet points
  • Direct references to API changes, system behaviors, and configuration updates

Implementation Steps

Follow these steps every time you prepare release notes for a new version:

1. Define the Release Scope

Identify everything included in the release:

• Features completed
• Tickets fixed
• Enhancements merged
• Internal APIs removed or modified
• Known issues resolved or newly identified

This list becomes your raw material.

2. Categorize the Changes

Group the scope items under consistent sections:

• New Features: New capabilities or modules
• Enhancements: Performance or UX improvements
• Bug Fixes: Corrected defects and stability fixes
• Breaking Changes: API or behavior changes that require developer action
• Deprecations: APIs to be removed in future versions
• Security: Permission, policy, or encryption updates
• Other: Documentation updates, internal refactors, tooling changes

3. Write Clear, Actionable Items

Use short, developer-oriented bullet points.

Good format examples:

• Added LocationUtils.getCurrentCity() API to simplify geolocation queries.
• Improved Push Kit initialization time by ~20%.
• Fixed a crash occurring when vibrate() was called before permission grant.
• Removed the deprecated HmsMapView component. Use MapViewComponent instead.

Avoid:

• Marketing language
• Vague statements like “various improvements”
• Overly detailed internal notes

4. Add Migration/Upgrade Notes (if needed)

Include mandatory developer actions when:

• API behavior changes
• Permissions change
• Data schema updates
• Module names or package paths change

Example:

Migration Note: Replace usages of oldApi.getToken() with authManager.requestToken() and update the import path to @kit/AuthKit.

5. Provide Configuration or Code Updates

If the release requires developers to modify code or configuration, include minimal examples.

Examples:

• Required imports
• New API call patterns
• Manifest permissions
• New module dependencies

6. Finalize the Document

• Keep the document short (ideal: 1 page per release).
• Maintain consistent version headers:

Code Snippet / Configuration

Sample:

## Version X.Y.Z (YYYY-MM-DD)

### New Features
- Added <feature> for <purpose>.
- Introduced <API/module> enabling <functionality>.

### Improvements
- Optimized <component> to reduce <latency/memory usage>.
- Updated UI behavior for <module> to improve <experience>.

### Bug Fixes
- Fixed issue where <condition> caused <crash/incorrect data>.
- Resolved synchronization error in <component> during <scenario>.

### Breaking Changes
- Removed <API>. Use <new API> instead.
- Updated permission model. Ensure the following permission is granted:
  ```ts
  // Example for ArkTS
  @ohos.permission.LOCATION

Written by Dogan Evci