diff --git a/amd/comgr/AGENT_CONVENTIONS.md b/amd/comgr/AGENT_CONVENTIONS.md index 81c266cd1f6a9..7fdea0725ebed 100644 --- a/amd/comgr/AGENT_CONVENTIONS.md +++ b/amd/comgr/AGENT_CONVENTIONS.md @@ -144,6 +144,25 @@ a feature PR. **Tests required.** Each PR is accompanied by tests aiming for 100% code coverage of the change being added. +**Bump the version when adding a public API.** Any commit that adds a +new `AMD_COMGR_API` function must bump the minor version in +`VERSION.txt` and tag the new prototype(s) with a fresh +`AMD_COMGR_VERSION_X_Y` macro in `include/amd_comgr.h.in`: + +- One bump per commit, not per function — a commit adding several APIs + bumps once and tags them all with the same new version. +- Never reuse the current version's macro for a new API in a later + commit. The previous version is already owned by whatever shipped it. +- Don't wait for an official release to bump. We don't know which + commit hash lands in each release, so the version must advance at the + moment the API is introduced. +- Add the symbol to `src/exportmap.in` under a version node matching the + new tag (e.g. `@amd_comgr_NAME@_X.Y { global: ...; } @prev;`), not the + previous node. +- `utils/check_api_consistency.py` only enforces `VERSION.txt >=` the + highest macro, so it will NOT catch a new API that reuses the current + version. Verify the bump by hand. + **Keep the branch rebased.** Resolve conflicts before requesting review.