Add documentation about platform tiers

Author: timfel

docs/site/01-docs.md

@@ -22,5 +22,6 @@ Below are the options you can set on contexts for GraalPy.
 {% gfm_docs ../user/Embedding-Permissions.md %}
 {% gfm_docs ../user/Tooling.md %}
 {% gfm_docs ../user/Troubleshooting.md %}
+{% gfm_docs ../user/Test-Tiers.md %}
 
 {% copy_assets ../user/assets %}

docs/user/README.md

@@ -1,8 +1,15 @@
 # Getting Started with GraalPy on the JVM
 
 You can use GraalPy with GraalVM JDK, Oracle JDK, or OpenJDK.
-You can easily add GraalPy to your Java application using Maven or Gradle build tools as shown below.
-Other build systems (Ant, Make, CMake, and so on) can also be used with a bit more manual work.
+To add GraalPy to your Java application, use Maven or Gradle as shown below.
+For other build systems (like Ant, Make, CMake, etc.), manual configuration may be required.
+
+### Platform support
+
+GraalPy is mostly written in Java and Python, but the Python package ecosystem is rich in native packages that need platform specific support via native libraries that expose platform-specific APIs.
+Our main operating system is Oracle Linux, the CPU architectures we focus on are AMD64 and ARM, and the main JDK we test is Oracle GraalVM.
+Windows and macOS with GraalVM JDK are less well tested, and outside of those combinations we target only basic test coverage.
+See [below](Test-Tiers.md) for a detailed breakdown.
 
 ## Maven
 
@@ -76,7 +83,7 @@ In order to distribute the resulting application for other systems, follow these
                 └── resources
     ```
 
-2. Open your project configuration file, _app/build.gradle_, and modify it as follows. 
+2. Open your project configuration file, _app/build.gradle_, and modify it as follows.
     - Include the GraalPy support and the [GraalVM Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) in the `dependencies` section:
         ```bash
         implementation("org.graalvm.polyglot:polyglot:24.2.0")
@@ -114,29 +121,29 @@ In order to distribute the resulting application for other systems, follow these
    id "org.graalvm.python" version "24.2.0"
    ```
 
-   - configure the GraalPy Gradle plugin:  
+   - configure the GraalPy Gradle plugin:
    ```bash
-   graalPy { 
+   graalPy {
       packages = ["termcolor==2.2"]
    }
    ```
-   
+
    5.2. In _settings.gradle_, add the following `pluginManagement` configuration.
    ```bash
    pluginManagement {
       repositories {
-         gradlePluginPortal()        
+         gradlePluginPortal()
       }
    }
    ```
 
    5.3. Update the file named _App.java_ as follows:
       ```java
       package interop;
-   
+
       import org.graalvm.polyglot.*;
       import org.graalvm.python.embedding.GraalPyResources;
-   
+
       class App {
       ...
       public static void main(String[] args) {
@@ -150,7 +157,7 @@ In order to distribute the resulting application for other systems, follow these
           }
       }
       ```
-   
+
 See also [Embedding Build Tools](Embedding-Build-Tools.md) for more information about the GraalPy Gradle Plugin.
 
 ## Ant, CMake, Makefile or Other Build Systems Without Direct Support for Maven Dependencies

docs/user/Test-Tiers.md

@@ -0,0 +1,53 @@
+# Detailed Test Tier Breakdown
+
+GraalPy test tiers are similar to [CPython Platform Support Tiers](https://peps.python.org/pep-0011/), but do not constitute or imply any commitment to support.
+
+Generally, running pure Python code on GraalPy without JIT is compatible with any recent JDK.
+However, support for native extensions, platform-specific APIs, and just-in-time compilation is more limited.
+
+Platform testing is organized into Tiers, each with specific goals.
+Tiers are identified by a "target tuple": `[CPU architecture]-[Operating System]-[libc]-[JDK]-[Java version]`.
+JDK names correspond to those used by [SDKMAN!](https://sdkman.io/).
+The term "graal" is used to refer to testing on both Oracle GraalVM and GraalVM Community Edition, including GraalVM Native Image.
+The following tables list tested platforms by tier.
+Platforms not listed are untested.
+
+**Tier 1**
+
+- CI failures block releases.
+- Changes which would break the main or release branches are not allowed to be merged; any breakage should be fixed or reverted immediately.
+- All core developers are responsible to keep main, and thus these platforms, working.
+- Platform-specific Python APIs and Python C extensions are fully tested.
+
+| Platform                         | Notes                      |
+|----------------------------------|----------------------------|
+| amd64-linux-glibc-graal-latest   | Oracle Linux 8 or similar. |
+| aarch64-linux-glibc-graal-latest | Oracle Linux 8 or similar. |
+
+**Tier 2**
+
+- CI failures block releases.
+- Changes which would break the main or release branches are not allowed to be merged; any breakage should be fixed or tests marked as skipped.
+- Circa 10% of tests running on Tier 1 platforms may be skipped on Tier 2 platforms.
+- Platform-specific Python APIs are fully tested; Python C extensions may have more issues than on Tier 1 platforms.
+
+| Platform                          | Notes                   |
+|-----------------------------------|-------------------------|
+| aarch64-macos-darwin-graal-latest | macOS on M-series CPUs. |
+
+**Tier 3**
+
+- CI failures block releases.
+- Changes which would break the main or release branches are not allowed to be merged; any breakage should be fixed or tests marked as skipped.
+- Circa 25% of tests running on Tier 1 platforms may be skipped on Tier 3.
+- Tests for platform-specific Python APIs and Python C extension are run, but not prioritized.
+
+| Platform                        | Notes                                        |
+|---------------------------------|----------------------------------------------|
+| amd64-macos-darwin-graal-latest | macOS on Intel CPUs running BigSur or newer. |
+| amd64-windows-msvc-graal-latest | Windows 11, Windows Server 2025, or newer.   |
+| amd64-linux-glibc-oracle-21     | JDK 21 is tested without JIT compilation.    |
+| aarch64-linux-glibc-oracle-21   | JDK 21 is tested without JIT compilation.    |
+| aarch64-macos-darwin-oracle-21  | JDK 21 is tested without JIT compilation.    |
+| amd64-macos-darwin-oracle-21    | JDK 21 is tested without JIT compilation.    |
+| amd64-windows-msvc-oracle-21    | JDK 21 is tested without JIT compilation.    |