---
name: preparing-release-changelog
description: Prepare the CHANGELOG.md for a Damus release by running the changelog script, curating the output, and committing the result. Covers prerequisites, known pitfalls (duplicate entries, reverted commits, truncated annotations, wrong version label), and the editing/commit steps.
---

# Preparing Release Changelog

## Description
Prepare the CHANGELOG.md for a Damus release by running the changelog script, curating the output, and committing the result. Covers prerequisites, known pitfalls (duplicate entries, reverted commits, truncated annotations, wrong version label), and the editing/commit steps.

## When to Use
- When preparing a new Damus release and the changelog needs to be updated
- When rebasing a release-changelog branch onto master and picking up new entries

## Overview

Damus uses a Python script (`devtools/changelog.py`) to assist in generating changelogs from git commit history. The changelog format follows [Keep a Changelog](https://keepachangelog.com/) conventions.

## Prerequisites

- Python 3 with `mako` and `requests` packages installed:
  ```
  pip install mako requests
  ```
- Access to the full git history (not a shallow clone). If needed, run:
  ```
  git fetch --unshallow origin
  git fetch origin tag <from_tag>
  ```

## Step 1: Identify the Commit Range

Find the tag for the previous release (e.g. `v1.16.1`) and the commit hash for the new release candidate:

```bash
git tag | sort -V | tail -20         # list recent tags
git rev-parse v1.16.1                # resolve a tag to its commit SHA
```

The commit range format is: `<from_tag>..<to_commit>`

Example: `v1.16.1..5cb8a49`

## Step 2: Run the Changelog Script

```bash
python3 devtools/changelog.py v1.16.1..5cb8a49
```

This scans git log for `Changelog-<section>:` annotations in commit messages, where `<section>` is one of: `added`, `changed`, `deprecated`, `fixed`, `removed`, `experimental`.

**Note:** The script derives the version label from the second argument with the first character stripped (intended for tag names like `v1.17` → `1.17`). When passing a bare commit hash, the version will be wrong—fix it manually when editing `CHANGELOG.md`.

## Step 3: Review and Clean Up the Raw Output

The script's output is a starting point that typically needs manual curation:

1. **Fix the version label:** Replace the auto-derived version (e.g. `cb8a49`) with the actual release version (e.g. `1.17`).

2. **Remove duplicate entries:** Some commits may appear after the previous release tag in `master` history but were already included in that previous release's `CHANGELOG.md` (e.g. cherry-picked features from a release branch). Cross-check against the existing `CHANGELOG.md` and remove duplicates.

3. **Remove reverted entries:** If a commit was later reverted, drop its `Changelog-*` entry. The revert commit may itself have a changelog entry explaining the fix—keep that instead.

4. **Fix truncated entries:** Commit messages with a very long first line can cause `Changelog-Fixed:` entries to be truncated. Check the raw `git log` output to find the full intent, or look up the PR for context.

5. **Verify the date:** Use the actual release date, not the commit date from the RC.

## Step 4: Update CHANGELOG.md

Prepend the new section to `CHANGELOG.md`, following the existing format:

```markdown
## [1.17] - YYYY-MM-DD

### Added

- Feature description (Author Name)


### Changed

- Change description (Author Name)


### Fixed

- Fix description (Author Name)



[1.17]: https://github.com/damus-io/damus/releases/tag/v1.17
```

Keep the existing `[version]: URL` reference link at the bottom of each section.

## Step 5: Commit the Changelog

```bash
git add CHANGELOG.md
git commit -s -m "v1.17 changelog"
```

## Tips

- **Changelog annotations in commits:** Contributors should include a line like `Changelog-Added: Description of feature` in their commit messages so the script can pick them up automatically.
- **`Changelog-None`:** Use this in commit messages that intentionally have no changelog entry (e.g. internal refactors, test fixes). The script ignores it.
- **Author attribution:** The script appends the git author name in parentheses. Keep these intact—they credit contributors.
- **Sections in the script** are: `added`, `changed`, `deprecated`, `fixed`, `removed`, `experimental`. Only sections that have at least one entry are rendered.