|
| 1 | +--- |
| 2 | +name: release-notes-update |
| 3 | +description: Generate or update release notes for a patch, minor, or major release, or just to update main. Run git-cliff, organize and edit the output per project conventions, and insert into CHANGES.md. |
| 4 | +argument-hint: [patch|minor|major|main] [prev-tag] |
| 5 | +--- |
| 6 | + |
| 7 | +Generate release notes for an OpenImageIO release. |
| 8 | + |
| 9 | +Arguments: `$ARGUMENTS` |
| 10 | +- First argument (optional): release type — `patch` (default), `minor`, `major`, or `main`. |
| 11 | +- Second argument (optional): previous release tag (e.g. `v3.1.2.0`). If omitted, find the most recent tag automatically. If the release type is `main`, instead of a tag, look for the last commit at which the CHANGES.md file was updated. |
| 12 | + |
| 13 | +## Steps |
| 14 | + |
| 15 | +1. **Determine the previous tag** if not provided: |
| 16 | + ``` |
| 17 | + git describe --tags --abbrev=0 |
| 18 | + ``` |
| 19 | + or look at recent tags: `git tag --sort=-version:refname | head -10`. |
| 20 | + However, if the "release type" is `main`, instead of a tag, just find |
| 21 | + the commit at which CHANGES.md was last updated. |
| 22 | + |
| 23 | +2. **Run git-cliff** to get raw commit data: |
| 24 | + ``` |
| 25 | + git cliff -c src/doc/cliff.toml <prev-tag>..HEAD > /tmp/cliff-out.md |
| 26 | + ``` |
| 27 | + Read `/tmp/cliff-out.md` to see the raw output. |
| 28 | + |
| 29 | +3. **Read CHANGES.md** to see the current top of the file and understand where to insert. |
| 30 | + |
| 31 | +4. **Format the release notes** according to the release type: |
| 32 | + |
| 33 | +### For patch releases: |
| 34 | + |
| 35 | +Follow the skeleton in `docs/dev/Changes-skeleton-patch.md`: |
| 36 | + |
| 37 | +``` |
| 38 | +Release X.Y.Z.W (Month DD, YYYY) -- compared to X.Y.Z.W-1 |
| 39 | +--------------------------------------------------------- |
| 40 | +- *category*: Description. [#NNNN](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/NNNN) (by author) |
| 41 | +``` |
| 42 | + |
| 43 | +Rules: |
| 44 | +- **Remove** the section headings git-cliff generates; patch notes are a flat |
| 45 | + list. |
| 46 | +- **Add conventional commit prefixes** to any "uncategorized" entries (those |
| 47 | + lacking a `feat:`, `fix:`, etc. prefix). |
| 48 | +- **Reorder** entries logically: feature enhancements first, then bug fixes, |
| 49 | + then build/CI fixes, then internal changes, then test improvements, then |
| 50 | + docs/admin. |
| 51 | +- **Omit** entries that are purely internal and too minor to matter to users. |
| 52 | + Ask for confirmation about entries you propose to omit. |
| 53 | +- Prefer to use author's actual name if known. If the name cannot be found, |
| 54 | + the GitHub userid can be used instead. |
| 55 | +- Omit the author if it is the project leader, Larry Gritz, unless he is not |
| 56 | + the dominant author (at least 75% of commits) in this release. |
| 57 | +- Keep entries to one line each. Be terse but informative. |
| 58 | +- Use the format `*subsystem*:` for the category prefix (e.g., image file |
| 59 | + format like `*exr*:`, utility like `*oiiotool*:`, class or API category like |
| 60 | + `*IBA*:`, or topic category such as `*build*:`, `*ci*:`, `*docs*:`). |
| 61 | +- We aim to make patch releases on the first day of each month. If we are |
| 62 | + within a few days of a month end, list the date as the beginning of the |
| 63 | + upcoming month. Ask for confirmation that this is the planned release date. |
| 64 | + |
| 65 | + |
| 66 | +### For minor or major releases: |
| 67 | + |
| 68 | +Follow the skeleton in `docs/dev/Changes-skeleton-major.md`. Sections: |
| 69 | + |
| 70 | +``` |
| 71 | +Release X.Y.0.0 (Month, YYYY) -- compared to X.Y-1 |
| 72 | +-------------------------------------------------- |
| 73 | +
|
| 74 | +### New minimum dependencies and compatibility changes: |
| 75 | +### ⛰️ Major new features and public API changes: |
| 76 | + * *New image file format support:* |
| 77 | + * *oiiotool new features and major improvements*: |
| 78 | + * *Command line utilities*: |
| 79 | + * *API changes* |
| 80 | + * Other notable new feature: |
| 81 | +### 🚀 Performance improvements: |
| 82 | +### 🐛 Fixes and feature enhancements: |
| 83 | +### 🔧 Internals and developer goodies |
| 84 | +### 🏗 Build/test/CI and platform ports: |
| 85 | + * CMake build system and scripts: |
| 86 | + * Dependency and platform support: |
| 87 | + * Testing and Continuous integration (CI) systems: |
| 88 | +### 📚 Notable documentation changes: |
| 89 | +### 🏢 Project Administration |
| 90 | +### 🤝 Contributors |
| 91 | +``` |
| 92 | + |
| 93 | +Note that the section outline may already be present, in which case you |
| 94 | +only need to fit items into the existing category outline. |
| 95 | + |
| 96 | +Rules: |
| 97 | +- Group commits into sections; within each section, cluster related items together. |
| 98 | +- When needed, expand terse one-liners into enough prose that users understand what changed and why it matters. |
| 99 | +- For `feat:` commits, make sure the feature is explained sufficiently — don't just copy the commit subject. |
| 100 | +- For `api:` or `api!:` commits, clearly call out what changed in the public API. |
| 101 | +- Include PR links and author attribution for every entry. |
| 102 | +- The notes should "tell the story" of the release, not just be a dump of commit subjects. |
| 103 | +- We aim to make major/minor releases approximately in October 1 of each year. If the anticipted release date is already in the file, don't change it. If it is not present, ask for confirmation of the planned release date. |
| 104 | + |
| 105 | +### For updating release notes in main: |
| 106 | + |
| 107 | +Rules: |
| 108 | +- Generally, follow the rules for "major/minor releases", except as noted in other items below. |
| 109 | +- Don't apply a new skeleton of category listings unless they are not present for the upcoming release. |
| 110 | + |
| 111 | +5. **Insert the formatted notes** into `CHANGES.md` in the appropriate place (as detailed below). Leave the existing content intact. |
| 112 | +- When updating `main` or preparing a `major` or `minor` release, insert the updates in the top section for the upcoming major/minor release. Insert a new set of category sections only if it's not already present. |
| 113 | +- When doing a `patch` release, insert the changes immediately above the last patch release of that branch, so that CHANGES.md lists releases in descending numerical (version) order. |
| 114 | +- When porting a set of release notes from a release branch into main, or from an older (obsolete) release branch to the current release branch, insert it into the right place to maintain overall descending order. |
| 115 | + |
| 116 | +6. **Double check that the notes are adequately descriptive.** (See more |
| 117 | + detailed description of this step below.) |
| 118 | + |
| 119 | +7. **Forward-port release notes from release branches if needed** |
| 120 | + |
| 121 | +8. **Show a summary** of what was inserted and ask the user to review before finalizing. |
| 122 | + |
| 123 | +## Forward-porting release notes |
| 124 | + |
| 125 | +Release notes may have been generated independently in main, and release |
| 126 | +branches. When updating one branch, we ensure that any changes from older |
| 127 | +branches have been incorporated. |
| 128 | + |
| 129 | +- When preparing `patch` release notes, check the CHANGES.md file in the |
| 130 | + "dev-X.(Y-1)" branch for the previous minor release family to identify any |
| 131 | + X.(Y-1).Z patch release notes that are not reflected in the current release |
| 132 | + notes that we are updating. |
| 133 | +- When updating `main` or doing a `major` or `minor` release, check the |
| 134 | + CHANGES.md file in both the "dev-X.(Y-1)" and "dev-X.(Y-2)" branches. |
| 135 | + Check whichever is newer of the local and remote copy of that branch, since |
| 136 | + the local one may have had release notes or its version in CMakeLists.txt |
| 137 | + updated, but not yet pushed to GitHub. |
| 138 | +- If any patch releases are present in the older dev branches checked, insert |
| 139 | + the release notes for those patch releases into the right positions in the |
| 140 | + current release notes that we are updating. |
| 141 | +- If a change is forward-ported in this manner and the same PR is an update in |
| 142 | + the current set of changes we are updating as our main task, document that |
| 143 | + in the current set of notes using the following convention: in the line of |
| 144 | + the notes, the explanation of the version where it appears should reflect |
| 145 | + the first version of all branches where it appeared, for example, `(3.2.0.0, |
| 146 | + 3.1.3.0, 3.0.8.0)` to indicate that the patch was added to each of those |
| 147 | + versions. The versions should be listed in descending order. |
| 148 | + |
| 149 | +## Useful abbreviations for category labels |
| 150 | + |
| 151 | +| Abbrev | Meaning | |
| 152 | +|--------|---------| |
| 153 | +| IB | ImageBuf | |
| 154 | +| IBA | ImageBufAlgo | |
| 155 | +| IC | ImageCache | |
| 156 | +| TS | TextureSystem | |
| 157 | +| oiiotool | the oiiotool command | |
| 158 | +| build | CMake/build system | |
| 159 | +| deps | Changes to accommodate dependency or toolchain changes | |
| 160 | +| ci | CI/GitHub Actions | |
| 161 | +| docs | documentation | |
| 162 | +| int | internal/refactor | |
| 163 | +| test | testsuite or unit tests | |
| 164 | +| HEADER.h | Developer utilities in a public header file | |
| 165 | + |
| 166 | +## Combining PRs into single entries |
| 167 | + |
| 168 | +To be more concise and easier to read, within a release's notes, related |
| 169 | +PRs/commits can be combined into a single bullet-point line, which would look |
| 170 | +like |
| 171 | +``` |
| 172 | +- *category*: Combined Description. [#NNNN1](URL) (by author1) [#NNNN2](URL2) (by author2) [#NNNN2](URL2) (by author2) |
| 173 | +
|
| 174 | +``` |
| 175 | +if fully combined, or if explained one by one, |
| 176 | +``` |
| 177 | +- *category*: Description 1 [#NNNN1](URL) (by author1), amendment 2, [#NNNN2](URL2) (by author2), amendment 3, [#NNNN3](URL3) (by author3) |
| 178 | +``` |
| 179 | +Choose the fully combined or explained one by one based on which is more clear |
| 180 | +to the reader. |
| 181 | + |
| 182 | +If the authors are all the same, only have the author designation at the end. |
| 183 | + |
| 184 | +Here are the cases where it's ok to combine commits in this way: |
| 185 | +- If it is clear that multiple PRs are part of the same feature or fix, |
| 186 | + consisting of an initial commit, and subsequent smaller changes or |
| 187 | + continuations of the same topic. |
| 188 | +- An initial commit, and a subsequent commit that is obviously a fix to a bug |
| 189 | + in the initial commit. |
| 190 | +- "CI" changes that all only add new cases to the test matrix. |
| 191 | +- "CI" changes that all only fix spontaneous breakages in the GitHub runners. |
| 192 | +- "Build" changes that are all just minor updates to versions of dependencies |
| 193 | + that we support or test against. |
| 194 | + |
| 195 | +Some more examples of combined commit messages: |
| 196 | + |
| 197 | +``` |
| 198 | + - feat: Add GPS metadata functionality for TIFF [PR1](PR URL 1) [PR2](PR URL 2) [PR3](PR URL 3) (by author). |
| 199 | + - ci: New CI variants for MSVS 2026 [PR1](PR URL 1) (by author1), VFX Platform 2027 [PR2](PR URL 2) (by author2). |
| 200 | + - ci: Various fixes for unexpected changes to GitHub Actions runners [PR1](PR URL 1), [PR2](PR URL 2) (by author) |
| 201 | + - build: Added support for gcc 15 [PR1](PR URL 1) (by author1), OpenEXR 3.5.1 [PR2](PR URL 2) (by author2), libtiff 4.8 [PR3](PR URL 3) (by author3). |
| 202 | +``` |
| 203 | + |
| 204 | +Always ask for confirmation before combining commits in this manner. Confirm |
| 205 | +separately for each proposed combination of a group of multiple original |
| 206 | +commits into a single commit. Give the user the opportunity to revise the |
| 207 | +combined description or request other changes for the grouping. |
| 208 | + |
| 209 | +## Double check that the notes are adequately descriptive |
| 210 | + |
| 211 | +For newly added items for this release, read the short descriptions provided |
| 212 | +by git-cliff, double check them against the full commit messages to be sure |
| 213 | +the one-line summary is adequate. If the summary is misleading, too brief and |
| 214 | +leaving out the fact that an important thing was changed, or not adequately |
| 215 | +capturing the scope of changes, feel free to propose an alternate wording that |
| 216 | +will make it more clear to readers what changed as a result of the PR. Ask for |
| 217 | +confirmation on these and explain why you felt the one-line description wasn't |
| 218 | +enough. |
| 219 | + |
| 220 | +One example of a case where this is needed is if the one line description |
| 221 | +merely mentions a new image processing capability by name, but the full commit |
| 222 | +message makes it clear that a new ImageBufAlgo API call was added, and also a |
| 223 | +new oiiotool command line argument was added, and that couldn't all be |
| 224 | +described in the one-line brief message of the commit. |
| 225 | + |
| 226 | +## Reference |
| 227 | + |
| 228 | +Full release procedures: `docs/dev/RELEASING.md` |
| 229 | +Patch skeleton: `docs/dev/Changes-skeleton-patch.md` |
| 230 | +Major skeleton: `docs/dev/Changes-skeleton-major.md` |
| 231 | +Example good patch notes: https://github.com/AcademySoftwareFoundation/OpenImageIO/releases/tag/v3.0.0.0 |
| 232 | +Example good major/minor notes: https://github.com/AcademySoftwareFoundation/OpenImageIO/releases/tag/v3.1.6.1 |
0 commit comments