|
| 1 | +--- |
| 2 | +name: release-notes |
| 3 | +description: Draft release notes for a new ORC version. Use when preparing a release to generate changelog and GitHub release body from git history. |
| 4 | +disable-model-invocation: true |
| 5 | +--- |
| 6 | + |
| 7 | +# Draft ORC Release Notes |
| 8 | + |
| 9 | +Guide for drafting release notes when preparing a new ORC release. |
| 10 | + |
| 11 | +## When to Use |
| 12 | + |
| 13 | +Use this skill when: |
| 14 | +- Preparing a new ORC release |
| 15 | +- The user asks to draft or write release notes |
| 16 | +- The user asks to prepare a changelog entry |
| 17 | + |
| 18 | +## Step 1: Gather Release Parameters |
| 19 | + |
| 20 | +Ask the user for: |
| 21 | +1. **New version number** (e.g., `v2.5.0`) |
| 22 | +2. **Release date** (default: today) |
| 23 | + |
| 24 | +Then determine the previous release tag automatically: |
| 25 | +```bash |
| 26 | +git tag --sort=-v:refname | head -1 |
| 27 | +``` |
| 28 | + |
| 29 | +## Step 2: Collect Git History |
| 30 | + |
| 31 | +Run these commands to gather the raw data (replace `<prev>` with the previous tag): |
| 32 | + |
| 33 | +```bash |
| 34 | +# Full commit log |
| 35 | +git log <prev>..HEAD --oneline |
| 36 | + |
| 37 | +# Contributors with commit counts |
| 38 | +git shortlog -sne <prev>..HEAD |
| 39 | + |
| 40 | +# New controller directories (compare directory listings) |
| 41 | +diff <(git ls-tree -d --name-only <prev> internal/controllers/ | sort) \ |
| 42 | + <(git ls-tree -d --name-only HEAD internal/controllers/ | sort) \ |
| 43 | + | grep '^>' |
| 44 | + |
| 45 | +# All authors who ever contributed before this release |
| 46 | +git log <prev> --format='%aN' | sort -u > /tmp/old-contributors.txt |
| 47 | + |
| 48 | +# Authors in this release |
| 49 | +git log <prev>..HEAD --format='%aN' | sort -u > /tmp/new-contributors.txt |
| 50 | + |
| 51 | +# First-time contributors |
| 52 | +comm -13 /tmp/old-contributors.txt /tmp/new-contributors.txt |
| 53 | +``` |
| 54 | + |
| 55 | +For each first-time contributor, find the PR number of their first contribution: |
| 56 | +```bash |
| 57 | +git log <prev>..HEAD --author="<name>" --oneline --reverse | head -1 |
| 58 | +``` |
| 59 | +Then look up the corresponding PR number from the merge commit message (format: `Merge pull request #NNN`). |
| 60 | + |
| 61 | +## Step 3: Categorize Changes |
| 62 | + |
| 63 | +Review every commit and sort into sections. Use these rules: |
| 64 | + |
| 65 | +### New controllers |
| 66 | +Commits that add a new controller directory under `internal/controllers/`. Format: |
| 67 | +``` |
| 68 | +- <Kind>: Manage <OpenStack service> <resource description> |
| 69 | +``` |
| 70 | +Examples: |
| 71 | +- `Keypair: Manage Nova SSH keypairs` |
| 72 | +- `Volume: Manage Cinder block storage volumes` |
| 73 | +- `Domain: Manage Keystone identity domains` |
| 74 | + |
| 75 | +### New features |
| 76 | +Feature additions or enhancements to existing controllers or infrastructure. When scoped to a specific controller, prefix with the controller name and colon: |
| 77 | +``` |
| 78 | +- <Controller>: <Description of the feature> |
| 79 | +``` |
| 80 | +Examples: |
| 81 | +- `Server: Added ability to specify SSH keypair` |
| 82 | +- `Added support for generating and publishing OLM bundle images` |
| 83 | + |
| 84 | +### Bug fixes |
| 85 | +Bug fixes, especially those referencing GitHub issues. Include the issue link when available: |
| 86 | +``` |
| 87 | +- <Description> (Fixes [#NNN](https://github.com/k-orc/openstack-resource-controller/issues/NNN)) |
| 88 | +``` |
| 89 | +Examples: |
| 90 | +- `Allow to use application credentials with access rules (Fixes [#596](https://github.com/k-orc/openstack-resource-controller/issues/596))` |
| 91 | +- `Documentation: Fixed examples in getting-started guide` |
| 92 | + |
| 93 | +### Breaking changes |
| 94 | +API incompatibilities or behavioral changes that require user action. Only include this section if there are breaking changes. List the specific type/field changes. |
| 95 | + |
| 96 | +### Update considerations |
| 97 | +Important information users need to know when upgrading. Only include this section when relevant (e.g., new minimum OpenStack version requirements). |
| 98 | + |
| 99 | +### Infrastructure improvements |
| 100 | +Group related items. Common categories: |
| 101 | +- Go version bumps |
| 102 | +- Dependency bumps (group into a single bullet: k8s libs, controller-runtime, gophercloud) |
| 103 | +- CI changes (OpenStack version support, new test infrastructure) |
| 104 | +- Documentation improvements |
| 105 | +- Tooling changes |
| 106 | + |
| 107 | +### Commits to skip |
| 108 | +Do NOT include in release notes: |
| 109 | +- Changes related to newly introduced controllers: if a controller is new in this release, its features and bug fixes are already implied by the "New controllers" entry and must not be duplicated in "New features" or "Bug fixes" |
| 110 | +- Dependabot/automated dependency bumps (summarize as a single infrastructure bullet) |
| 111 | +- Merge commits |
| 112 | +- Code style fixes, typo fixes, linting fixes |
| 113 | +- Internal refactoring with no user-visible impact |
| 114 | + |
| 115 | +## Step 4: Write the Opening Summary |
| 116 | + |
| 117 | +The opening summary is optional. Include one when: |
| 118 | +- The release has a strong unifying theme |
| 119 | +- There is a major new capability worth highlighting |
| 120 | + |
| 121 | +Format: 1-2 sentences before the first section heading. |
| 122 | + |
| 123 | +Example from v2.3.0: |
| 124 | +> This release brings support for updating resources after creation for all relevant controllers. You can now modify your OpenStack infrastructure in-place without recreating resources, enabling true lifecycle management for production workloads. |
| 125 | +
|
| 126 | +## Step 5: Produce Two Outputs |
| 127 | + |
| 128 | +### Output 1: GitHub Release Body |
| 129 | + |
| 130 | +This is the markdown body for the GitHub release (used with `gh release create`). |
| 131 | + |
| 132 | +Template: |
| 133 | +```markdown |
| 134 | +## What's Changed |
| 135 | + |
| 136 | +<!-- Optional: opening summary paragraph --> |
| 137 | + |
| 138 | +### New controllers |
| 139 | + |
| 140 | +- Kind1: Description |
| 141 | +- Kind2: Description |
| 142 | + |
| 143 | +### New features |
| 144 | + |
| 145 | +- Controller: Feature description |
| 146 | +- Feature description |
| 147 | + |
| 148 | +### Bug fixes |
| 149 | + |
| 150 | +- Fix description (Fixes [#NNN](https://github.com/k-orc/openstack-resource-controller/issues/NNN)) |
| 151 | + |
| 152 | +### Infrastructure improvements |
| 153 | + |
| 154 | +- Category: Description |
| 155 | + |
| 156 | +## New Contributors |
| 157 | + |
| 158 | +- @username made their first contribution in [#NNN](https://github.com/k-orc/openstack-resource-controller/pull/NNN) |
| 159 | + |
| 160 | +**Full Changelog**: [<prev>...<new>](https://github.com/k-orc/openstack-resource-controller/compare/<prev>...<new>) |
| 161 | +``` |
| 162 | + |
| 163 | +Notes: |
| 164 | +- Omit any section that has no entries (e.g., skip "Breaking changes" if there are none) |
| 165 | +- The "New Contributors" section lists first-time contributors with their GitHub username and first PR |
| 166 | +- The "Full Changelog" link uses the GitHub compare URL between the two tags |
| 167 | + |
| 168 | +### Output 2: Changelog Entry |
| 169 | + |
| 170 | +This is prepended to `website/docs/changelog.md`, right after the `# Changelog` heading. |
| 171 | + |
| 172 | +Template: |
| 173 | +```markdown |
| 174 | +## v<MAJOR>.<MINOR> - <Month> <Day>, <Year> |
| 175 | + |
| 176 | +<!-- Optional: opening summary paragraph --> |
| 177 | + |
| 178 | +### New controllers |
| 179 | + |
| 180 | +- Kind1: Description |
| 181 | + |
| 182 | +### New features |
| 183 | + |
| 184 | +- Feature description |
| 185 | + |
| 186 | +### Bug fixes |
| 187 | + |
| 188 | +- Fix description (Fixes [#NNN](https://github.com/k-orc/openstack-resource-controller/issues/NNN)) |
| 189 | + |
| 190 | +### Infrastructure improvements |
| 191 | + |
| 192 | +- Description |
| 193 | +``` |
| 194 | + |
| 195 | +Notes: |
| 196 | +- The heading uses `v<MAJOR>.<MINOR>` (no patch version) with the full date |
| 197 | +- No "New Contributors" or "Full Changelog" sections |
| 198 | +- Otherwise identical content to the GitHub release body |
| 199 | + |
| 200 | +## Step 6: Review Checklist |
| 201 | + |
| 202 | +Before presenting the draft to the user, verify: |
| 203 | + |
| 204 | +- [ ] All new controller directories have corresponding entries in "New controllers" |
| 205 | +- [ ] All GitHub issue references use the correct issue number and full URL |
| 206 | +- [ ] First-time contributors are identified with correct GitHub usernames and PR numbers |
| 207 | +- [ ] Dependency bumps are summarized (not listed individually) |
| 208 | +- [ ] The compare URL uses the correct previous and new tag names |
| 209 | +- [ ] Sections with no entries are omitted entirely |
| 210 | +- [ ] Each bullet is concise (one line, no multi-sentence descriptions) |
| 211 | +- [ ] Controller-scoped items are prefixed with the controller name |
| 212 | +- [ ] The changelog entry heading uses the short version (vX.Y) and the full date |
| 213 | +- [ ] The opening summary (if included) accurately represents the release highlights |
| 214 | + |
| 215 | +## Style Guidelines |
| 216 | + |
| 217 | +- Use past tense for completed work ("Added", "Fixed", "Bumped") |
| 218 | +- Capitalize the first word of each bullet |
| 219 | +- End bullets without a period |
| 220 | +- Group related changes into a single bullet when possible (especially dependency bumps) |
| 221 | +- Use the OpenStack service name to describe new controllers (Nova, Neutron, Cinder, Keystone, Glance) |
| 222 | +- Reference specific version numbers for dependency bumps (e.g., "gophercloud to v2.9.0") |
0 commit comments