Setup Changelog

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Create a root CHANGELOG.md for a repository by reconstructing its release history from git tags, GitHub Releases, and the actual code changes between them — not by guessing or leaving placeholder entries.

Purpose

iru-setup-changelog backfills one Keep a Changelog entry per past release, using whichever source is most reliable for that release: a non-empty GitHub Release body if one exists (lightly reformatted rather than copied verbatim), a WordPress plugin/theme readme.txt == Changelog == entry for that version, or a derived analysis of git log/diffs between tags otherwise. It skips changes that don’t affect users of the project (tooling, CI, formatting-only diffs) unless they’re genuinely the entire content of a release, in which case it says so plainly rather than inventing something more exciting. This skill is primarily a bootstrap, and it announces whether it is creating the changelog from scratch or updating an existing one. Step 1 checks whether CHANGELOG.md (or an equivalent like CHANGELOG.rst/HISTORY.md/ CHANGELOG.txt) already exists at the repository root. If it does, the skill warns, lists the tagged releases that have no version heading in the file, and asks (unless on-existing pre-answers) whether to Keep as is (the original skip behaviour; recommended when nothing is missing), Update (append only the missing releases in version order plus their compare links, never rewriting, reordering, or reformatting an existing entry; not offered for .rst/.txt files), or Replace (rebuild the whole file from history, losing hand-written entries; for a differently-named file it writes a new root CHANGELOG.md and leaves the old one for the user to delete).

The skill is stack-agnostic: version tags (with or without a leading v) are the release markers whatever the build system — Maven/Gradle, npm, Laravel, WordPress, PrestaShop, Python (pyproject.toml) — and a -SNAPSHOT/-dev/PEP 440 .dev0 version found in-tree is never used as a heading. A WordPress readme.txt changelog does not count as an existing changelog (it is owned by the WordPress.org release process and is never edited), but it is read as a source; a plugin released only through WordPress.org SVN with no git tags can have its readme.txt entries backfilled instead of an Unreleased-only file (undated if the text gives no dates).

Purpose group

Repository Bootstrap

Plugin

Shipped by the iru-core plugin of the ai-catalog marketplace (install with /plugin install iru-core@ai-catalog; see Plugins).

Invocation

/iru-setup-changelog

Optionally followed by an args line, e.g. on-existing: update, when called by an orchestrator.

Inputs

Argument Required Description Default

Argument	Required	Description	Default
`on-existing`	No	`ask`, `keep`, `update`, or `replace` — how to treat an existing changelog. For scripted runs: Step 1 still prints its warning but applies the value without asking. `mode: existing` alone does not mean "update silently"; Step 1 still asks unless `on-existing` says otherwise.	`ask`
other `key: value` lines	No	Ignored. The content itself comes entirely from the repository’s actual release history: git tags (`git for-each-ref`), and, if hosted on GitHub with `gh` available and authenticated, each tag’s GitHub Release body via `gh release view`.	Not applicable.

on-existing

ask, keep, update, or replace — how to treat an existing changelog. For scripted runs: Step 1 still prints its warning but applies the value without asking. mode: existing alone does not mean "update silently"; Step 1 still asks unless on-existing says otherwise.

ask

other key: value lines

Ignored. The content itself comes entirely from the repository’s actual release history: git tags (git for-each-ref), and, if hosted on GitHub with gh available and authenticated, each tag’s GitHub Release body via gh release view.

Not applicable.

Outputs

CHANGELOG.md at the repository root, in Keep a Changelog format, with one [<version>] - <date> section per past release (newest first, an empty [Unreleased] at the very top) plus a compare-link reference section if the remote is GitHub.
When a changelog already exists, the outcome depends on the option chosen in Step 1: Keep as is makes no changes (the report only notes the file was kept and any missing releases); Update inserts the missing releases at their newest-first positions, adds their compare links following the file’s existing link style, and corrects only the [Unreleased] link’s base tag, leaving every existing line byte-for-byte unchanged (the diff is shown in the report); Replace rebuilds the file as for a from-scratch run.
If no git tags exist at all, the skill asks the user whether to create a minimal file with just an ## [Unreleased] section, or stop entirely rather than inventing version numbers (a WordPress plugin/theme with a readme.txt changelog is offered a backfill from it instead).
A closing report that starts by restating the mode (created from scratch, or kept as is / updated / replaced and whether that came from the user or on-existing), then: how many releases were reconstructed (or, under Update, appended) and their version range, which releases used a GitHub Release body versus derived commit/diff analysis, any release noted as tooling/docs-only, and whether compare links were included or omitted.

Execution flow

flowchart TD A["Start /iru-setup-changelog"] --> A0["Step 0: Resolve on-existing from args\n(default ask)"] A0 --> B{"Step 1: CHANGELOG.md (or\nequivalent) already exists?"} B -- no --> B1["Announce: creating from scratch"] B1 --> C B -- yes --> B2["Announce: updating existing changelog;\nlist missing releases; warn and ask\nKeep / Update / Replace\n(or apply on-existing)"] B2 -- Keep as is --> Z["Stop. No changes made;\nreport missing releases"] B2 -- Update --> U["Read existing file;\nrestrict to missing releases"] U --> C B2 -- Replace --> C["Step 2: Discover release history\n(git tags, GitHub Releases via gh)"] C --> D{"Any tags found?"} D -- no --> E["Ask user: minimal Unreleased-only\nfile (or readme.txt backfill for WordPress),\nor stop entirely?"] D -- yes --> F["Step 3: For each release,\ndetermine source of content\n(GitHub Release body, readme.txt entry,\nor derived diffs);\nlong tag history fans out to\nchange-summarizer agents"] F --> G["Step 4: Compose each release's\nKeep a Changelog subsections"] G --> H["Step 5: Determine each version's\ndate and ordering"] H --> I["Step 6: Write CHANGELOG.md\n(Update: insert missing sections only)"] I --> J["Step 7: Report"] E --> J

Dependencies

Invokes

None — iru-setup-changelog does not call any other skill in this catalog, but see "Related agents" below for a sub-agent it delegates to.

Invoked by

Setup CLI Repository — bootstraps or updates the root CHANGELOG.md of a command-line tool repository via the iru-isolated-skill-executor agent.
Setup Java Library Repository — Step 7 runs iru-setup-changelog with no args, working entirely from the repository’s own git tag/GitHub Release history.
Setup TypeScript Repository — Step 9, root CHANGELOG.md, via the iru-isolated-skill-executor agent.
Setup Java Spring Boot — Step 9, CHANGELOG.md.
Setup PHP Repository — Step 9, root CHANGELOG.md, via the iru-isolated-skill-executor agent.
Setup Quarkus Repository — Step 7, root CHANGELOG.md from tag history, via the iru-isolated-skill-executor agent.
Setup Android Repository — Step 8: bootstraps or updates the root CHANGELOG.md, invoked with no args (only on-existing, when supplied) since it works from the repository’s own git tag/GitHub Release history.
Setup Swift Repository — Step 9: bootstraps the root CHANGELOG.md, invoked with no args (only on-existing when supplied) since it works from the repository’s own git tag/GitHub Release history; position relative to Steps 5–8 doesn’t matter functionally.
Setup KMP Repository — Step 8: bootstraps or updates the root CHANGELOG.md via the iru-isolated-skill-executor agent, invoked with no args (only on-existing when supplied) since it works from the repository’s own git tag/GitHub Release history.

Related agents

iru-change-summarizer — Step 3, dispatched one per past release (or small batch of releases) instead of reading every diff inline, when the repository’s tag history is long enough (a few dozen releases or more) that doing so serially would be context-heavy.

Source

SKILL.md on GitHub — the file this page was generated from.