| name | update-changelog |
| description | Updates or adds entries to CHANGELOG.md based on the changes in the current branch. Use this skill whenever the user asks to update the changelog, add a changelog entry or document changes. |
Update CHANGELOG
Overview
You are writing changelog entries for the Readium Kotlin Toolkit.
The audience is app developers who integrate this toolkit – not contributors.
Entries tell them what changed and, when necessary, how to adapt their code.
CHANGELOG format
The file is at CHANGELOG.md. New entries go under ## [Unreleased].
Structure within [Unreleased]:
## [Unreleased]
### Added
#### Playground
#### Shared
#### Navigator
### Deprecated
...
### Changed
#### Playground
...
### Fixed
...
Omit the sub-section heading for cross-cutting changes.
Entry style
- Start each bullet with a past-tense verb or a noun phrase: "Added", "Fixed", "The X now…"
- Be concise — one to three lines maximum per entry.
- Mention the public API surface (type name, method name) in backticks.
- Do NOT explain implementation details; focus on what the developer observes or must do.
- Do NOT document defensive validation (e.g. rejecting out-of-range values). Only document the positive behavior change that developers care about (e.g. "decimal values are now supported").
- Link to an existing guide when the change is non-trivial to adopt:
- Migration steps:
[the migration guide](docs/migration-guide.md) (or a specific anchor)
- New feature guide:
[the user guide](docs/guides/...) if a guide exists
- When the API is gated behind an experimental SPI, mention it.
- Prefix Fixed entries with the GitHub issue:
- [#NNN](URL) Fixed ....
Attributions
For external contributions, we want to attribute the author. Follow these instructions:
- run
gh pr view --json number,title,url,author to get the PR for the current branch and its author's login.
- Check if the author is a maintainer with
gh api repos/readium/kotlin-toolkit/collaborators --jq '.[].login'.
- Only add a contribution credit if the author is not a maintainer, appending
(contributed by [@login](PR URL)).
Process
- Read the diff — run
git log --oneline <base>..HEAD and git diff <base>..HEAD to understand what changed. Use develop as the base branch unless told otherwise.
- Read the existing
[Unreleased] section to avoid duplicating entries that are already there.
- Read
docs/Migration Guide.md to check whether the changes are already documented there; if so, link to the relevant section in the changelog entry.
- Draft entries grouped by section and sub-section. When in doubt whether something is worth documenting:
- Public API additions/changes/removals → always document
- Bug fixes visible to the developer → document
- Internal refactoring with no public API impact → skip
- Test-only changes → skip
- Insert the new entries into
CHANGELOG.md under ## [Unreleased], creating sections/sub-sections as needed. Preserve the existing content.
- Review the changelog entries to make sure the mentioned APIs are correct.
- Show the user the diff of what you added and ask for confirmation before finalizing.
Examples of good entries
### Added
#### Playground
* New `Playground` iOS app – a minimal SwiftUI sample demonstrating how to use the Readium Swift Toolkit and to test its API.
* `Recipes/` contains self-contained and explained code you can reuse in your own application.
* `App/` folder contains the scaffolding (file management, navigation, error handling) needed to run the Playground.
#### Shared
* Added support for SVG covers in `ResourceCoverService`. SVG images can now be used as publication covers and are rendered to bitmaps (contributed by [@grighakobian](https://github.com/readium/swift-toolkit/pull/751)).
* `Publication` has a new experimental `coverData(accepting:)` API that returns the raw bytes and media type of the cover, useful for storing the original cover without re-encoding.
### Fixed
#### Navigator
* [#721](https://github.com/readium/swift-toolkit/issues/721) Fixed position of EPUB decorations when using the paragraph indent preference.
