[Comgr] Document API versioning rule in AGENT_CONVENTIONS.md

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.