--- name: generate-changelog-0ee1c1040be1 description: Generate or update the root umbrella CHANGELOG.md and per-crate CHANGELOG.md files from cargo-dist style git release tags, GitHub release context, and commit history. Use when Codex is asked to create changelogs, compare changes between independent crate releases, prepare release notes, fill an Unreleased section, regenerate crate changelogs, or refresh the root changelog for winterbaume. --- # Generate Changelog ## Overview Create concise, human-edited changelogs for winterbaume's independently released crates. Per-crate changelogs at `crates//CHANGELOG.md` are the authoritative detailed record; the root `CHANGELOG.md` is an umbrella summary and index across crate releases. Each release is bounded by cargo-dist style tags named `-v` such as `winterbaume-s3-v0.1.1`. The skill ships two helper scripts under `scripts/` that do the mechanical bullet-extraction work, so the model's job is the editorial pass — summarising behaviour, collapsing repeated updates, dropping implementation trivia per the rules below. - `scripts/draft_section.py --crate [--next-version ] [--date ] [--from-ref ]` — emits a draft per-crate section to stdout. Resolves the latest `-v` tag, walks `git log --first-parent ..HEAD -- crates//`, buckets commits by conventional-commit prefix into the canonical `Added / Changed / Fixed / Terraform / Documentation / Tests / Internal` sections, skips `chore: release …` noise. Omit `--next-version` for an `## Unreleased` heading. - `scripts/draft_umbrella_entry.py --entry :[:] ... [--date ]` — emits a dated root-CHANGELOG section linking to each crate's own changelog. `` is optional and renders as a parenthesised qualifier ( `initial release`, `pinned`, etc. ). Both scripts write only to stdout; the caller decides where the markdown lands. ## Workflow 1. **Establish the release model.** - Read `RELEASE.md` and the root `Cargo.toml` `[workspace.metadata.release]` section. - Treat tags matching `-v` as release tags, following cargo-dist conventions. - Scope detailed changelog generation to one crate unless the user asks for all crates, a specific list of crates, or the root umbrella changelog. - Derive the crate name from the package name, not the directory name. For example, package `winterbaume-s3` uses tags like `winterbaume-s3-v0.1.1` and changelog path `crates/winterbaume-s3/CHANGELOG.md`. - Remember that crates are independently versioned, so do not compare one crate's tag against another crate's tag. - Treat root `CHANGELOG.md` as a cross-crate overview that summarises release batches by date and links to per-crate changelogs. 2. **Inspect existing state.** - Check `git status --short` before editing and do not overwrite unrelated user changes. - For each target crate, work on `crates//CHANGELOG.md`. - If the crate changelog exists, preserve manually authored sections and the existing style unless it is clearly broken. - If the crate changelog does not exist, create it with `# Changelog` and an `## Unreleased` section when there are unreleased changes. - When generating the umbrella changelog, work on root `CHANGELOG.md`. - If root `CHANGELOG.md` does not exist, create it as an overview with links to crate changelogs instead of copying all crate-level release notes. - If local tags may be stale and current release accuracy matters, fetch tags only after following the session's network and approval rules. 3. **Discover release boundaries.** - List tags with enough metadata to group releases: ```bash git for-each-ref --sort=creatordate --format='%(refname:short)%09%(creatordate:short)%09%(objectname:short)%09%(subject)' refs/tags ``` - Filter to release tags, normally `winterbaume-*-v*`. - For each target crate, keep only tags whose prefix exactly matches that package name plus `-v`. - Sort that crate's tags by version or creation date, then use only adjacent tags from that same crate for historical ranges. - If the target crate has no release tags, create or update only its `Unreleased` section and state that no tagged releases were found if the user expected historical release sections. - For root `CHANGELOG.md`, collect all release tags, then group releases by tag date. Keep the individual crate tag identity inside each dated section. 4. **Collect changes for each range.** - **Preferred path:** run `scripts/draft_section.py` for the target crate. It already does the `git log --first-parent`, the conventional-commit bucketing, and the heading rendering described in the rest of this step. Take its stdout as the mechanical draft, then polish per the editorial rules in §7. ```bash # Releasable section (dated heading): python3 .agents/skills/generate-changelog/scripts/draft_section.py \ --crate winterbaume-s3 --next-version 0.1.2 --date 2026-05-18 # Unreleased section (no version yet): python3 .agents/skills/generate-changelog/scripts/draft_section.py \ --crate winterbaume-s3 ``` - **When the script doesn't fit** ( e.g. you need a historical range between two specific tags rather than `tag..HEAD` ), fall back to `git log` directly. Compare the previous release tag for the same crate to the current tag: ```bash git log --first-parent --date=short --format='%H%x09%ad%x09%s' .. ``` - For the first tagged release of a crate, use the repository root or the earliest relevant commit as the lower boundary ( pass it via `--from-ref` to the script ). - For `Unreleased`, compare the newest release tag for that crate to `HEAD` — the script does this by default when `--next-version` is omitted. - Filter each range to changes relevant to the target crate and shared files that affect it. Inspect: - The crate directory, usually `crates//`. - Shared workspace files that affect package contents or behaviour, such as `Cargo.toml`, `Cargo.lock`, `tools/`, `.github/workflows/`, `README.md`, `docs/`, and `.agents/docs/`, when the commit meaningfully changes that crate's release. - Inspect touched paths for ambiguous commits with `git show --stat --oneline ` or `git show --name-only --format=fuller `. - If GitHub PR or release context is needed and available, use it to clarify intent, but do not rely on remote metadata when local commits are sufficient. 5. **Write the changelog.** - Write each target crate's changelog to `crates//CHANGELOG.md`. - Use reverse chronological order: `Unreleased` first, then newest release sections for that crate. - Prefer this section shape: ```markdown # Changelog ## Unreleased ### Added - ... ## v0.1.1 - 2026-04-29 ### Fixed - ... ``` - Use the crate tag date as the release date. Section headings should use the crate version (`## v0.1.1 - YYYY-MM-DD`), because the file path already identifies the crate. - Use categories only when they have entries. Good categories for this repository are `Added`, `Changed`, `Fixed`, `Terraform`, `Documentation`, `Tests`, and `Internal`. - Include commit hashes only when they add useful traceability; avoid turning the changelog into a commit dump. 6. **Write the umbrella changelog when requested.** - Write the root changelog to `CHANGELOG.md`. - Keep it shorter than the per-crate files. It should help readers find what changed across the project without duplicating every detail. - Use `scripts/draft_umbrella_entry.py` to render a dated section from a list of `name:version[:note]` entries — it owns the link format and bullet shape. ```bash python3 .agents/skills/generate-changelog/scripts/draft_umbrella_entry.py \ --entry winterbaume-s3:0.1.2 \ --entry winterbaume-sqs:0.1.2:pinned \ --date 2026-05-18 ``` - Prefer this section shape: ```markdown # Changelog This file summarises notable winterbaume releases. Detailed crate-level notes live in each crate's `CHANGELOG.md`. ## Unreleased - See crate changelogs for unreleased crate-specific work. ## 2026-04-29 - `winterbaume-s3` v0.1.1: Implemented bucket tagging APIs. See [`crates/winterbaume-s3/CHANGELOG.md`](crates/winterbaume-s3/CHANGELOG.md). - `winterbaume-sqs` v0.1.1: Fixed queue attribute persistence. See [`crates/winterbaume-sqs/CHANGELOG.md`](crates/winterbaume-sqs/CHANGELOG.md). ``` - Group entries by date when several crate tags were created on the same day. - Link to crate changelogs when they exist. If generating root `CHANGELOG.md` before per-crate files exist, either create the relevant crate changelogs too or avoid links to missing files. - Use one bullet per crate release unless a release needs two bullets to separate major user-facing themes. - Include workspace-wide release tooling, documentation, or infrastructure changes in root `CHANGELOG.md` only when they affect release consumers or multiple crates. ## Editorial Rules - Summarise behaviour, not implementation trivia. "Implemented S3 bucket tagging APIs" is better than listing every helper function touched. - Mention generated source, model, or coverage report churn only when it changes user-visible support or release contents. - Collapse repeated crate/service updates into one clear bullet when they share the same intent. - Omit changes that only affect other crates, even if they happened between the same dates. - Do not let root `CHANGELOG.md` become the authoritative source for crate details; keep detailed notes in per-crate files and summarise at the root. - Preserve issue and PR references that appear in commit messages. - Exclude pure release metadata commits such as `chore: release ...` unless the release itself is the only notable change. - Use British English in repo-authored prose, except for API names, Rust terms, or quoted commit titles. - Do not invent entries. If a range is unclear, inspect the diff or say in the final response what could not be determined. ## Validation - Re-read every edited `crates//CHANGELOG.md` after editing to check ordering, dates, duplicate entries, and Markdown structure. - Re-read root `CHANGELOG.md` after editing to ensure every linked crate changelog path exists. - Run `git diff -- CHANGELOG.md crates/*/CHANGELOG.md` or a narrower pathspec and verify the diff only changes intended changelog content. - If the task only updates changelog files, no Rust build is required. --- Source attribution: moriyoshi Original project: https://github.com/moriyoshi/winterbaume/blob/69fed1d7fb0eb9a2738ff3274197c7591129c4cb/.agents/skills/generate-changelog/SKILL.md License: Apache-2.0 License information: https://www.apache.org/licenses/LICENSE-2.0 Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ## Additional upstream notices generate-changelog-0ee1c1040be1/DAVEAI-UPSTREAM-NOTICE Winterbaume Copyright 2025 Winterbaume contributors This product includes software developed at https://github.com/getmoto/moto ======================================================================= Moto - Mock AWS Services ======================================================================= Copyright 2012 Steve Pulec Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Winterbaume used moto as a reference implementation for AWS service mock behaviour and ported many of its Python test cases into Rust integration tests. The moto source is available at https://github.com/getmoto/moto. Moto is written by Steve Pulec with contributions from: Zach Smith, Dilshod Tadjibaev, Dan Berglund, Lincoln de Sousa, mhock, Ilya Sukhanov, Lucian Branescu Mihaila, Konstantinos Koukopoulos, attili, JJ Zeng, Jon Haddad, Andres Riancho, Michael Ossareh, JeffMGreg, Hugo Lopes Tavares, Chris St. Pierre, Frank Mata, Clint Ecker, Richard Eames, Kevin Glisson, Shawn Falkner-Horine, David Baumgold, Rory-Finnegan, Bobby Impollonia, Ralfas, Omer Katz, Joseph Lawson, Trey Tacon, Peter, Tyler Sanders, Gary Dalton, Chris Henry, Mike Fuller, Andy, Mike Grima, Marco Rucci, Zack Kourouma, Pior Bastida, Dustin J. Mitchell, Jean-Baptiste Barth, Tom Viner, Justin Wiley, Adam Stauffer, Guy Templeton, Michael van Tellingen, Jessie Nadler, Alex Morken, Clive Li, Jim Shields, William Richard, Alex Casalboni, Jon Beilke, Bendeguz Acs, Craig Anderson, Robert Lewis, Kyle Jones, Mickaël Schoentgen, Ariel Beck, Roman Rader, Bryan Chen, Jonas Bulik, Rita Cheung, David Acevedo, Damon Williams The full contributor list is available at https://github.com/getmoto/moto/blob/master/AUTHORS.md. ======================================================================= AWS API Models ======================================================================= Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Winterbaume vendors a snapshot of the official AWS API Smithy models under vendor/api-models-aws/ to drive its in-tree wire-type and serialiser code generation. The upstream LICENSE and NOTICE files are preserved alongside the vendored models. The upstream source is available at https://github.com/aws/api-models-aws. # Mega AI Hub resource metadata Creator / publisher: moriyoshi Original project: https://github.com/moriyoshi/winterbaume/blob/69fed1d7fb0eb9a2738ff3274197c7591129c4cb/.agents/skills/generate-changelog/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Product Management Roles: Backend Developer, DevOps / SRE, Product Manager Specialties: Backend Tools: GitHub Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 7b7d36d05540c4bc336c7cc05863ec38031bd937d66fa4297873a31f7b87788e