add compatibility notes (#238)

* update README with compatibility notes

* minor wordsmithing

* clarify when to use tagged or released OpenCL API headers

.github/workflows/linux.yml

@@ -1,6 +1,12 @@
 name: Linux
 
-on: [push, pull_request]
+on:
+  push:
+    paths-ignore:
+      - '**/*.md'
+  pull_request:
+    paths-ignore:
+      - '**/*.md'
 
 jobs:
   compatibility:

.github/workflows/macos.yml

@@ -1,6 +1,12 @@
 name: MacOS
 
-on: [push, pull_request]
+on:
+  push:
+    paths-ignore:
+      - '**/*.md'
+  pull_request:
+    paths-ignore:
+      - '**/*.md'
 
 jobs:
   compatibility:

.github/workflows/windows.yml

@@ -1,6 +1,12 @@
 name: Windows
 
-on: [push, pull_request]
+on:
+  push:
+    paths-ignore:
+      - '**/*.md'
+  pull_request:
+    paths-ignore:
+      - '**/*.md'
 
 jobs:
   compatibility:

README.md

@@ -98,6 +98,23 @@ may include the OpenCL API headers as follows:
 #include <CL/opencl.h>
 ```
 
+## Compatibility Notes
+
+OpenCL values backward compatibility and in most cases an application using an
+older version of the OpenCL API headers can seamlessly update to a newer version
+of the OpenCL API headers.  In rare cases, though, the OpenCL API headers may
+break backward compatibility:
+
+* Very rarely, there may be bugs or other issues in the OpenCL API headers that
+  cannot be fixed without breaking compatibility.
+* The OpenCL API headers for provisional features or provisional extensions may
+  be changed in a way that breaks compatibility.
+
+Applications or libraries that require stable OpenCL API headers are encouraged
+to use tagged or released OpenCL API headers.  We will do our best to document
+any breaking changes in the description of each release.  The OpenCL API headers
+are tagged at least as often as each OpenCL specification release.
+
 ## Directory Structure
 
 ```