ort-release-notes

# ONNX Runtime Release Notes Use this skill to produce a consistent release-note draft from commit history and contributor metadata. ## When To Use Use this skill when you need to: - Draft release notes for a full ONNX Runtime release - Draft release notes for a scoped component (e.g., in-tree plugin EP) release - Select a release profile by preset name instead of manually supplying path/version files - Add PR links to highlight bullets - Build a human-only contributor acknowledgment list from contributor metadata ## Required Inputs Collect these inputs from the user or infer from context: 1. `preset`: release profile name (for example, `ort`, `webgpu-plugin-ep`, `cuda-plugin-ep`) 2. `base_ref`: previous release tag 3. `target_ref`: release commit/tag/branch tip Optional inputs: - `version` override - `output_dir` override ## Presets Read preset definitions from [presets.json](./presets.json). The config defines shared output defaults: 1. `outputDirPattern` 2. `draftFileName` Each preset defines: 1. `displayName`: reader-facing product or component name 2. `versionFile` 3. `pathsFile` (nullable): file of git pathspecs to filter to, one per line. Use `:(top)` to anchor an entry at repo root. Example presets: 1. `ort` (full ONNX Runtime) 2. `webgpu-plugin-ep` (scoped WebGPU Plugin EP) 3. `cuda-plugin-ep` (scoped CUDA Plugin EP) ### CUDA Plugin EP Scope The `cuda-plugin-ep` preset uses the pathspecs in `plugin-ep-cuda/paths.txt` to scope release-note changes. ## Workflow 1. Determine release mode. - Select preset and load configuration from [presets.json](./presets.json). - Use the preset's `displayName` whenever the release-note content names the product or component. The preset key is internal and must not appear in published content. - If preset has `pathsFile`, run in scoped mode. Otherwise run full mode. 2. Resolve version, in this order: 1. explicit `version` input 2. value from preset `versionFile` 3. Resolve output directory, referred to as `resolved_output_dir` after this step. The output directory contains contributor artifacts and the release notes draft. Resolve it in this order: 1. explicit `output_dir` input 2. shared `outputDirPattern` rendered with preset name and resolved version 4. Gather metadata. - If the output directory is missing or lacks contributor artifacts, generate them with `tools/python/compile_contributors.py`. - Generation can take a while because it scans commit history and fetches PR metadata. - Use `--paths-file` only when preset has a `pathsFile`. - If existing contributor artifacts are reused, verify `resolved_output_dir/logs.txt` matches base/target before trusting them. 5. Read `resolved_output_dir/detail.csv` as the primary source for PR numbers, titles, authors, target commits, and cherry-pick mapping. - Use `resolved_output_dir/logs.txt` for contributor summary context and base/target verification. - Use `git log` only as a fallback sanity check when artifacts are present but incomplete or suspect. - Check PRs with unexpectedly large author lists for rebased history that imported unrelated commits. Replace those authors with the actual PR author or authors before building contributor acknowledgments; do not credit authors solely because they authored an unrelated imported commit. For example, PR #28299, the rebased history contains unrelated commits and co-author metadata. 6. Build highlight categories. - Full ORT example categories: performance, model/operator support, execution providers, API/languages, reliability/security, build/packaging/tooling, docs/dev workflow. - Scoped mode: narrow categories to the component domain. 7. Draft markdown. - Write the release-note draft to `resolved_output_dir/<draftFileName>`. - Contents: - Intro sentence - `## Highlights` - Inline PR links on every highlight bullet - `## Contributors` - Optional scope note for scoped-component releases - Use the preset's reader-facing `displayName`, not the internal preset key. - Describe the scope in reader-facing terms, such as "commits affecting WebGPU Plugin EP code and packaging." - AI disclaimer if AI drafted - Do not mention presets, `pathsFile`, configuration files, or other release-note-generation implementation details in the release-note content. - Do not refer to the release notes as a "draft" in their content. "Draft" is only an internal workflow and file-naming concept. 8. Build contributors section. - Start from `detail.csv` output - Include humans only - Exclude bots/agents (for example: `github-actions[bot]`, `app/copilot-swe-agent`, `claude`) - Sort alphabetically 9. Validate draft quality. - Every highlight bullet has at least one PR link - PRs are traceable to metadata or git history - Contributor list is human-only and alphabetical - Scope is correct for full vs component release ## PowerShell Command Patterns ### compile_contributors.py Full ORT metadata: ```powershell python .\tools\python\compile_contributors.py \ --base <previous_tag> \ --target <target_ref> \ --dir <resolved_output_dir> ``` Scoped metadata: ```powershell python .\tools\python\compile_contributors.py \ --base <previous_tag> \ --target <target_ref> \ --dir <resolved_output_dir> \ --paths-file <paths_file> ``` ## Style and Policy Default policy unless release owners override: 1. Treat the range as changes since the previous release. 2. Keep PR links inline with highlight claims. 3. Keep contributor acknowledgments human-only and best effort. 4. Include an AI disclaimer when highlights are AI drafted. 5. Use GitHub Releases pages as preferred style references. E.g., [ORT 1.28 release page](https://github.com/microsoft/onnxruntime/releases/tag/v1.28.0). 6. Prefer preset-driven configuration over ad-hoc path/version arguments. 7. Use a single `output_dir` for contributor artifacts, logs, and the release-note draft.