release-notes-update

---
name: release-notes-update
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.
argument-hint: [patch|minor|major|main] [prev-tag]
---

Generate release notes for an OSL release.

Arguments: `$ARGUMENTS`
- First argument (optional): release type — `patch` (default), `minor`, `major`, or `main`.
- 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.

## Steps

1. **Determine the previous tag** if not provided:
   ```
   git describe --tags --abbrev=0
   ```
   or look at recent tags: `git tag --sort=-version:refname | head -10`.
   However, if the "release type" is `main`, instead of a tag, just find
   the commit at which CHANGES.md was last updated.

2. **Run git-cliff** to get raw commit data:
   ```
   git cliff -c src/doc/cliff.toml <prev-tag>..HEAD > /tmp/cliff-out.md
   ```
   Read `/tmp/cliff-out.md` to see the raw output.

3. **Required, do not skip:** Look up the GitHub user ID for each author (use
   `gh pr view NNNN --repo AcademySoftwareFoundation/OpenImageIO --json
   author` — the login is discernable from the posted PR, but not from the
   local commit). Rewrite every git-cliff author credit from `(by First
   Last)` to the combined form `(by @githubid / First Last)` before drafting
   the formatted notes in step 5. This applies to patch, minor, major, and
   main updates alike — the combined format is the standard for every
   release type, not just an example in the patch skeleton. Only fall back to
   a single form — `(by @githubid)` or `(by First Last)` — if the other half
   genuinely cannot be found; don't skip the github lookup just because the
   real name is already known from the local commit.

4. **Read CHANGES.md** to see the current top of the file and understand where to insert.

5. **Format the release notes** according to the release type:

### For patch releases:

Follow the skeleton in `docs/dev/Changes-skeleton-patch.md`:

```
Release X.Y.Z.W (Month DD, YYYY) -- compared to X.Y.Z.W-1
---------------------------------------------------------
- *category*: Description. [#NNNN](https://github.com/AcademySoftwareFoundation/OpenShadingLanguage/pull/NNNN) (by author)
```

Rules:
- **Remove** the section headings git-cliff generates; patch notes are a flat
  list.
- **Add conventional commit prefixes** to any "uncategorized" entries (those
  lacking a `feat:`, `fix:`, etc. prefix).
- **Reorder** entries logically: feature enhancements first, then bug fixes,
  then build/CI fixes, then internal changes, then test improvements, then
  docs/admin.
- **Omit** entries that are purely internal and too minor to matter to users.
  Ask for confirmation about entries you propose to omit.
- Author credit is `(by @githubid / Full Name)` per step 3 above. Use just
  `(by @githubid)` or `(by Full Name)` only if the other half truly can't be
  found — don't drop the githubid merely because the name is already known.
- Omit the author if it is the project leader, Larry Gritz, unless he is not
  the dominant author (at least 75% of commits) in this release.
- Keep entries to one line each. Be terse but informative.
- Use the format `*subsystem*:` for the category prefix (e.g., back end target
  such as `*optix*:` or `*batch*:`, utility like `*testrender*:` or
  `*osltoy*:`, class or API category like `*ShadingSystem*:`, or topic
  category such as `*build*:`, `*ci*:`, `*docs*:`).
- We aim to make patch releases on the first day of each month. If we are
  within a few days of a month end, list the date as the beginning of the
  upcoming month. Ask for confirmation that this is the planned release date.


### For minor or major releases:

Follow the skeleton in `docs/dev/Changes-skeleton-major.md`. Sections:

```
Release X.Y.0.0 (Month, YYYY) -- compared to X.Y-1
--------------------------------------------------

### New minimum dependencies, toolchain, and compatibility changes:
### ✏️  OSL Language, standard library, and oslc compiler (for shader writers):
### ⛰️  API changes and new ShadingSystem features (for renderer writers):
### ☀️  testshade/testrender/osltoy improvements
### 🐛/🔧  Internals: fixes, improvements, and developer concerns
### 🏗  Build/test/CI and platform ports
  * CMake build system and scripts:
  * Dependency and platform support:
  * Testing and Continuous integration (CI) systems:
### 📚  Notable documentation changes:
### 🏢  Project Administration
### 🤝  Contributors
```

Note that the section outline may already be present, in which case you
only need to fit items into the existing category outline.

Rules:
- Group commits into sections; within each section, cluster related items together.
- When needed, expand terse one-liners into enough prose that users understand what changed and why it matters.
- For `feat:` commits, make sure the feature is explained sufficiently — don't just copy the commit subject.
- For `api:` or `api!:` commits, clearly call out what changed in the public API.
- Include PR links and author attribution for every entry, in the combined
  `(by @githubid / Full Name)` form from step 3.
- The notes should "tell the story" of the release, not just be a dump of commit subjects.
- 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.

### For updating release notes in main:

Rules:
- Generally, follow the rules for "major/minor releases", except as noted in other items below.
- Don't apply a new skeleton of category listings unless they are not present for the upcoming release.

5. **Insert the formatted notes** into `CHANGES.md` in the appropriate place (as detailed below). Leave the existing content intact.
- 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.
- 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.
- 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.

6. **Double check that the notes are adequately descriptive.** (See more
   detailed description of this step below.)

7. **Forward-port release notes from release branches if needed**

8. **Show a summary** of what was inserted and ask the user to review before finalizing.

## Forward-porting release notes

Release notes may have been generated independently in main, and release
branches. When updating one branch, we ensure that any changes from older
branches have been incorporated.

- When preparing `patch` release notes, check the CHANGES.md file in the
  "dev-X.(Y-1)" branch for the previous minor release family to identify any
  X.(Y-1).Z patch release notes that are not reflected in the current release
  notes that we are updating.
- When updating `main` or doing a `major` or `minor` release, check the
  CHANGES.md file in both the "dev-X.(Y-1)" and "dev-X.(Y-2)" branches.
  Check whichever is newer of the local and remote copy of that branch, since
  the local one may have had release notes or its version in CMakeLists.txt
  updated, but not yet pushed to GitHub.
- If any patch releases are present in the older dev branches checked, insert
  the release notes for those patch releases into the right positions in the
  current release notes that we are updating.
- If a change is forward-ported in this manner and the same PR is an update in
  the current set of changes we are updating as our main task, document that
  in the current set of notes using the following convention: in the line of
  the notes, the explanation of the version where it appears should reflect
  the first version of all branches where it appeared, for example, `(3.2.0.0,
  3.1.3.0, 3.0.8.0)` to indicate that the patch was added to each of those
  versions. The versions should be listed in descending order.

## Useful abbreviations for category labels

| Abbrev | Meaning |
|--------|---------|
| build | CMake/build system |
| deps | Changes to accommodate dependency or toolchain changes |
| ci | CI/GitHub Actions |
| docs | documentation |
| int | internal/refactor |
| test | testsuite or unit tests |
| HEADER.h | Developer utilities in a public header file |

## Combining PRs into single entries

To be more concise and easier to read, within a release's notes, related
PRs/commits can be combined into a single bullet-point line, which would look
like
```
- *category*: Combined Description. [#NNNN1](URL) (by author1) [#NNNN2](URL2) (by author2)  [#NNNN2](URL2) (by author2)

```
if fully combined, or if explained one by one,
```
- *category*: Description 1 [#NNNN1](URL) (by author1), amendment 2, [#NNNN2](URL2) (by author2), amendment 3, [#NNNN3](URL3) (by author3)
```
Choose the fully combined or explained one by one based on which is more clear
to the reader.

If the authors are all the same, only have the author designation at the end.

Here are the cases where it's ok to combine commits in this way:
- If it is clear that multiple PRs are part of the same feature or fix,
  consisting of an initial commit, and subsequent smaller changes or
  continuations of the same topic.
- An initial commit, and a subsequent commit that is obviously a fix to a bug
  in the initial commit.
- "CI" changes that all only add new cases to the test matrix.
- "CI" changes that all only fix spontaneous breakages in the GitHub runners.
- "Build" changes that are all just minor updates to versions of dependencies
  that we support or test against.

Some more examples of combined commit messages:

```
  - feat: Add GPS metadata functionality for TIFF [PR1](PR URL 1) [PR2](PR URL 2) [PR3](PR URL 3) (by author).
  - ci: New CI variants for MSVS 2026 [PR1](PR URL 1) (by author1), VFX Platform 2027 [PR2](PR URL 2) (by author2).
  - ci: Various fixes for unexpected changes to GitHub Actions runners [PR1](PR URL 1), [PR2](PR URL 2) (by author)
  - 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).
```

Always ask for confirmation before combining commits in this manner. Confirm
separately for each proposed combination of a group of multiple original
commits into a single commit. Give the user the opportunity to revise the
combined description or request other changes for the grouping.

## Double check that the notes are adequately descriptive

For newly added items for this release, read the short descriptions provided
by git-cliff, double check them against the full commit messages to be sure
the one-line summary is adequate. If the summary is misleading, too brief and
leaving out the fact that an important thing was changed, or not adequately
capturing the scope of changes, feel free to propose an alternate wording that
will make it more clear to readers what changed as a result of the PR. Ask for
confirmation on these and explain why you felt the one-line description wasn't
enough.

## Reference

Full release procedures: `docs/dev/RELEASING.md`
Patch skeleton: `docs/dev/Changes-skeleton-patch.md`
Major skeleton: `docs/dev/Changes-skeleton-major.md`
Example good patch notes: https://github.com/AcademySoftwareFoundation/OpenShadingLanguage/releases/tag/v1.15.2.0
Example good major/minor notes: https://github.com/AcademySoftwareFoundation/OpenShadingLanguage/releases/tag/v1.15.0.0

More agent context in AcademySoftwareFoundation/OpenShadingLanguage

2 other files this repository gives its agents.