OpenParable
Skip to content
← Back to skills

Preparing Release Changelog

Productivity
preparing-release-changelog

Preparing Release Changelog is an Agent Skill for productivity published in the damus-io/damus repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/damus-io/damus/blob/HEAD/.agents/skills/preparing-release-changelog/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/preparing-release-changelog, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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 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:

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

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:

## [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

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.