amdsmi-changelog-automation

name	amdsmi-changelog-automation
description	Check and generate changelog entries for amd-smi. Use when: reviewing PRs for changelog updates, generating release notes, checking CHANGELOG.md compliance.

Changelog Automation — amd-smi

Location & Headings

CHANGELOG.md at the amd-smi project root. Entries group under ## amd_smi_lib for ROCm <MAJOR>.<MINOR>.<PATCH> headings (no ## [Unreleased]). Allowed subsection headings — anything else is a violation (e.g. ### Fixed, which this repo does not use): Added, Changed, Removed, Optimized, Resolved Issues, Upcoming Changes, Known Issues. Bug fixes go under Resolved Issues, deprecations under Upcoming Changes.

Which Release Does an Entry Belong To?

An entry belongs to release V if its authoring commit is in the range pin(V-1)..pin(V) — the diff between two consecutive ROCm release points, not the heading it currently sits under.

A "pin" is the rocm-systems commit that ROCm/TheRock records for a release. TheRock tags drop the patch component: section 7.14.0 → tag therock-7.14 (confirm exact names with gh release list --repo ROCm/TheRock; V-1 is the tag immediately below V).

pin() {  # rocm-systems commit pinned by a TheRock tag; origin/develop if the tag is absent
  gh api "repos/ROCm/TheRock/git/trees/$1" 2>/dev/null \
    | python3 -c "import sys,json;d=json.load(sys.stdin);print(next(t['sha'] for t in d.get('tree',[]) if t['path']=='rocm-systems'))" 2>/dev/null \
    || echo origin/develop
}

A tagged release is frozen at its pin: pin(therock-<V>) is the exact state that shipped as ROCm <V>. A commit merged after the pin did not ship in <V> and belongs to the next release — even when <V> is still the top heading and no <next> section exists yet (create it and move the entry). TOO NEW (below) against a tagged section is always a real misfile.

Auditing a Section

Bound the section by its own version — HIGH=pin(therock-<V>), never origin/develop by default (pin() returns origin/develop itself if <V> isn't tagged yet). Flag any blamed commit outside pin(<V-1>)..pin(<V>); checking only one bound misses entries merged after V shipped.

git fetch origin >/dev/null 2>&1
LOW=$(pin therock-<MAJOR.MINOR of V-1>)
HIGH=$(pin therock-<MAJOR.MINOR of V>)
read START END < <(awk '/^## amd_smi_lib for ROCm/{n++; if(n==1)s=NR; else if(n==2){print s, NR-1; exit}}' CHANGELOG.md)

# placement — flag commits outside pin(V-1)..pin(V)
git blame -L "$START,$END" -s CHANGELOG.md | awk '{print $1}' | sed 's/^\^//' | sort -u \
  | while read h; do
      git merge-base --is-ancestor "$h" "$LOW"  2>/dev/null && { echo "TOO OLD (earlier release): $h"; continue; }
      git merge-base --is-ancestor "$h" "$HIGH" 2>/dev/null || echo "TOO NEW (later release): $h"
    done

# taxonomy — flag disallowed section headings
sed -n "${START},${END}p" CHANGELOG.md | grep -nE '^### ' \
  | grep -vE '### (Added|Changed|Removed|Optimized|Resolved Issues|Upcoming Changes|Known Issues)'

# format — bold headline bullets must end with two trailing spaces; JIRA IDs never in entry text
sed -n "${START},${END}p" CHANGELOG.md | grep -nP '^- \*\*.*\*\*[^ ]*$'         # any match = a headline bullet missing its two trailing spaces
sed -n "${START},${END}p" CHANGELOG.md | grep -nE 'ROCM-[0-9]+|SWDEV-[0-9]+'    # JIRA belongs only in the PR JIRA ID section

• TOO OLD — commit shipped in an earlier release; the entry is a misfile/duplicate.
• TOO NEW — commit merged after V's pin; move the entry to the next release's section (create a new top ## amd_smi_lib for ROCm <next> block if none exists).
• Entry type vs heading — no command catches this: read each entry's wording against the change-type table below. A valid heading can still hold a wrong-type entry (e.g. a deprecation filed under ### Changed instead of Upcoming Changes).

Section for Each Change Type

Change	Section	Entry needed?
New public API / new CLI flag or subcommand	Added	Yes
Bug fix (incl. user-visible build fix)	Resolved Issues	Yes
Breaking API change	Changed (+ migration note)	Yes
Other behavior/output change	Changed	Yes
Performance / tooling improvement	Optimized	Yes
Deprecation (still functional)	Upcoming Changes	Yes
Internal refactor / test-only / docs-only / style-only	—	No

Entry Rules

• One bullet per logical change, starting with the affected component (API name, CLI subcommand, or module).
• Breaking changes include migration guidance.
• JIRA/issue refs only in the PR JIRA ID section, never in entry text.
• Bold headline bullets must end with two trailing spaces (··) so Sphinx keeps the headline and its sub-bullets on separate lines:

  - **Fixed `amd-smi static` hang on gfx1153**.··
    - Added 60-second timeout to `amdsmi_init()`.