chore(dev): use pre-commit to identify api changes

.pre-commit-config.yaml

@@ -105,6 +105,27 @@ repos:
         pass_filenames: false
         require_serial: true
         files: ^llama_stack/apis/|^docs/openapi_generator/
+      - id: openapi-spec-check
+        name: OpenAPI spec change validator
+        entry: bash
+        args:
+          - -c
+          - |
+            SPEC_PATH="docs/_static/llama-stack-spec.yaml"
+
+            # if the generated spec is part of the staged commit (cached), require [API CHANGE]
+            if git diff --name-only --cached -- "$SPEC_PATH" | grep -q .; then
+              if ! grep -q "\[API CHANGE\]" "$(git rev-parse --git-dir)/COMMIT_EDITMSG"; then
+                echo "ERROR: $SPEC_PATH changed but commit message does not include '[API CHANGE]'."
+                echo "Please include '[API CHANGE]' in the commit message when modifying the public API spec."
+                exit 1
+              fi
+            fi
+          - --
+        language: system
+        pass_filenames: false
+        require_serial: true
+        stages: [commit-msg]
       - id: check-workflows-use-hashes
         name: Check GitHub Actions use SHA-pinned actions
         entry: ./scripts/check-workflows-use-hashes.sh

CONTRIBUTING.md

@@ -42,7 +42,7 @@ uv run --env-file .env -- pytest -v tests/integration/inference/test_text_infere
 We use [pre-commit](https://pre-commit.com/) to run linting and formatting checks on your code. You can install the pre-commit hooks by running:
 
 ```bash
-uv run pre-commit install
+uv run pre-commit install -t pre-commit -t commit-msg
 ```
 
 After that, pre-commit hooks will run automatically before each commit.
@@ -57,6 +57,8 @@ uv run pre-commit run --all-files
 Before pushing your changes, make sure that the pre-commit hooks have passed successfully.
 ```
 
+A note about API changes: We use a commit-msg hook and OpenAPI spec generation to detect API changes. When changing the API, you must add `[API CHANGE]` to your commit message to pass the check.
+
 ## Discussions -> Issues -> Pull Requests
 
 We actively welcome your pull requests. However, please read the following. This is heavily inspired by [Ghostty](https://github.com/ghostty-org/ghostty/blob/main/CONTRIBUTING.md).