Documentation Types — Release Notes for Version Communication

In this tutorial, you will learn about Documentation Types. We cover key concepts, practical examples, and best practices to help you master this topic.

Release notes communicate what changed between software versions. They help users decide whether to upgrade and understand what new capabilities or fixes they receive. This documentation type is critical for maintaining user trust during product evolution.

In this lesson, you will learn how to write release notes that are complete, accurate, and useful for different audiences.

What You'll Learn

You will understand the release note documentation type, structure release notes for different audiences, and automate release note generation from commit history.

Why It Matters

Users upgrading from an old version need to know what changed. Without clear release notes, they assume nothing changed and miss critical updates. Poor release notes cause upgrade hesitation and support tickets.

Real-World Use

DodaTech publishes release notes for every DodaZIP version with categorized changes and Migration instructions. Users upgraded within the first week of each release because they understood exactly what they were getting.

flowchart LR
  A[New Version] --> B[Release Notes]
  B --> C[New Features]
  B --> D[Bug Fixes]
  B --> E[Breaking Changes]
  B --> F[Deprecations]
  C --> G[User Decision]
  G --> H{Upgrade?}
  H -->|Yes| I[Migration Steps]
  H -->|No| J[Stay on Current]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Release Note Structure

Every release note should include the version number and release date. Categorize changes into sections: new features, improvements, bug fixes, breaking changes, and deprecations.

Each entry should describe the change from the user's perspective. What was the problem? What changed? How does the user benefit? Include the issue or Pull Request number for reference.

Breaking changes need special attention. Explain what changed, why it changed, and how the user should update their code. Include migration examples.

## DodaZIP 2.1.0 Release Notes

### New Features
- Added LZ4 compression algorithm for 2x faster compression times
- New verify flag checks archive integrity after creation
- Parallel compression for multi-core systems (experimental)

### Bug Fixes
- Fixed crash when compressing files with Unicode filenames
- Fixed memory leak in streaming decompression
- Fixed incorrect progress reporting for files over 4 GB

### Breaking Changes
- Dropped support for Python 3.8 (minimum is now 3.9)
- The level flag now accepts 1-9 instead of 1-6

### Deprecations
- The compress_all function is deprecated. Use Compressor with batch_mode=True instead.

Automation

Manual release notes are time-consuming and error-prone. Automate the collection of changes from commit messages, pull requests, and issue tracking.

Maintain a changelog file in your Repository. Each pull request should add an entry to the changelog. Before release, format the entries into release notes.

Use conventional commit messages to categorize changes automatically. Commits prefixed with feat or fix can be parsed into new features and bug fixes sections.

# Generate release notes from git log
git log --oneline --no-merges v2.0.0..v2.1.0

# Expected output:
# fe9a12b feat: add LZ4 compression algorithm
# b3c45d6 fix: handle Unicode filenames in compression
# a7b89c0 fix: memory leak in streaming decompression
# e5f67g8 breaking: drop Python 3.8 support
# h1i23j4 feat: add verify flag for integrity checking

Common Mistakes

1. No Categories

A single list of changes without categorization forces readers to scan everything looking for what matters to them.

2. Vague Descriptions

Fixed performance issues without specifics. Users do not know if their use case is affected.

3. Missing Breaking Changes

Hiding breaking changes in a list of bug fixes. Breaking changes must be called out prominently with migration instructions.

4. Too Technical

Writing release notes for developers when the audience includes end users. Use language appropriate for each audience.

5. No Dates

Release notes without dates make it impossible to know how old a version is.

6. Missing Migration Steps

Breaking changes without migration steps leave users stuck. Every breaking change needs a clear upgrade path.

7. No Deprecation Timeline

Deprecating features without announcing when they will be removed. Users need time to migrate.

Practice Questions

1. What categories should release notes include?

New features, improvements, bug fixes, breaking changes, and deprecations. Each category helps different audiences find relevant information.

2. Why must breaking changes be called out prominently?

Users need to know if upgrading will require code changes. Hiding breaking changes causes unexpected failures.

3. How can release notes be automated?

Using conventional commit messages parsed from git history. Each pull request adds a changelog entry that gets formatted into release notes.

4. What information should each release note entry include?

The change from the user perspective, the problem it solves, and the issue or PR number for reference.

5. Challenge: Write release notes for a hypothetical v3.0.0 of a library you use. Include three new features, four bug fixes, two breaking changes with migration steps, and one deprecation with removal timeline.

FAQ

Mini Project

Collect the last three releases of a project you use. Analyze their release notes against the best practices in this lesson. Rewrite one set of release notes with proper categorization, clear descriptions, and migration steps where needed.

What's Next

Next: FAQ Documentation