Update Changelog Entries

Use this skill to update changelog entries for one or more crates in this workspace.

When to Use

• The user asks to update or add a CHANGELOG.md entry
• A code change is complete and needs release notes
• A crate version changed and changelog updates are needed
• A behavioral change in the shell should be documented for users

Outcome

Produce changelog updates that:

• Use an [x.y.z] - Unreleased section for each affected crate
• Add or update the release-link reference for each newly added unreleased section
• Use standard categories: Added, Changed, Deprecated, Removed, Fixed, Security
• Describe the user or developer impact clearly and concretely
• Stay consistent with crate versions in Cargo.toml
• Order bullets by importance and relatedness, not insertion time

Procedure

1. Identify affected crates. Use the diff to find which crates changed. Treat each crate independently.

2. Confirm target version for each crate. Read <crate>/Cargo.toml and capture the current forecast version. Do not bump versions again if already bumped for unreleased work. If the version does not look like the next semver release for the current changes, stop and ask the user how to resolve the mismatch before editing changelogs.

3. Open <crate>/CHANGELOG.md. Find an existing [x.y.z] - Unreleased section matching the crate version. If missing, create it near the top using repository conventions. When creating a new unreleased section, also add a link definition near the end of the changelog that points to the corresponding release page.

4. Classify each change. Map each change to exactly one primary category:

   • Added: New feature or capability
   • Changed: Behavior change that is not purely a bug fix
   • Deprecated: Still available but planned for removal
   • Removed: Deleted behavior or API
   • Fixed: Bug correction
   • Security: Vulnerability or hardening update

5. Write concise, user-meaningful bullets. State what changed, concretely. Avoid internal-only jargon unless the crate is developer-facing. For yash-cli/CHANGELOG.md, keep entries focused on user-visible behavior and avoid implementation details aimed at crate developers. Order bullets by importance first, then by relatedness within a category.

   Keep each bullet minimal, but do state the value. Say what changed, and say what it gives the user when that is not already obvious — a new convenience, a problem it solves, a capability it unlocks. "The portable option now catches more portability problems" is worth writing, because it tells the reader what they gain. What to leave out is anything that merely recites facts without conveying value:

   • The reason, when it follows from the change itself and the purpose of the feature involved. A new restriction under the portable option, for instance, needs no explanation of the POSIX requirement behind it — checking portability is what that option is for.
   • Background and comparative detail, such as how other shells or older versions behave.
   • Guidance the shell itself prints. If the error message already tells the user to write -- instead, the changelog does not repeat it.
   • What the change does not affect, unless a reader would otherwise expect it to change.
   • Internal implementation history, such as where an item used to live, that it was previously private, or which module it was extracted from. Readers of a changelog see only the crate's public surface as it is now; where a newly public item came from tells them nothing they can act on.

   The manual under docs/src is where the full rationale and the portable alternative belong; link there rather than restating them.

   Represent net release state, not commit history. Before adding a new bullet, scan the existing Unreleased section for bullets that cover the same feature or area. If a prior bullet already describes behavior that the current change replaces or refines, update or replace that bullet to reflect the final outcome. The Unreleased section must read as if describing the next release in full, not as a running log of intermediate commits. For example, if "feature A was added" is already in Unreleased and the current change renames A to B, replace the bullet with "Added B" rather than appending "Renamed A to B".

6. Handle cross-crate behavior. If shell-observable behavior changed, also update yash-cli/CHANGELOG.md even when implementation lives in another crate.

7. Keep scope clean. Only add entries for changes in the current work. Do not rewrite historical sections.

8. Validate consistency. Ensure each edited changelog version matches the corresponding crate version and wording is factual.

Decision Points

• If change is not user-visible but affects crate users (library API or semantics): add an entry to that crate changelog.

• If change is observable in shell behavior: add or update entry in yash-cli/CHANGELOG.md.

• If Cargo.toml version does not appear semver-appropriate for the pending changes: ask the user whether to adjust the version, scope, or changelog framing.

• If the current change modifies behavior already documented in the Unreleased section (i.e., something added or changed since the last release): update or replace the existing bullet to describe the final outcome. Do not append a second bullet that contradicts or supersedes an earlier one.

• If a change could fit multiple categories: choose the category users will search first, then keep the bullet focused.

• If no relevant changelog section exists for the target unreleased version: create [x.y.z] - Unreleased before adding bullets.

Quality Checks

• Every affected crate has matching changelog coverage.
• Category headings are consistent with repository style.
• Bullets describe behavior or impact, not vague implementation activity.
• Where a change gives users something new, the bullet says so; where it does not, it stays minimal.
• No bullet explains a reason that follows from the change itself and the purpose of the feature involved, recounts how other shells or older versions behave, repeats guidance the shell already prints in its error message, or states what the change leaves unchanged without a reason to.
• In yash-cli/CHANGELOG.md, bullets stay user-facing and avoid deep internal details.
• Bullets are ordered by importance and relatedness, not by edit time.
• No duplicate bullets across categories.
• yash-cli changelog is updated when user-visible shell behavior changed.
• No contradiction between changelog text and code changes.
• No bullet in the Unreleased section is superseded or contradicted by another bullet in the same section. Each feature or fix appears exactly once, described as it will exist in the next release rather than as a sequence of intermediate steps.

Output Format

When reporting back to the user:

• List edited changelog files
• Summarize bullets added per file
• Mention any crates checked but intentionally not updated
• Call out any follow-up needed (for example, unclear release framing)

Limits

• Do not invent behavior changes that are not present in code or tests.
• Do not add speculative future work to changelog entries.
• Do not mix unrelated changes into one bullet.