Make notes in metadata.toml explicit.

Author: timfel

docs/site/03-compatibility.md

@@ -69,7 +69,7 @@ img.pylogo {
             xhr.onload = function () {
                 if (this.status === 200) {
                     const patches = [];
-                    const lines = this.responseText.trim().split('\n');
+                    const lines = txt.split('\n');
                     var currentPatch = null;
                     for (let i = 0; i < lines.length; i++) {
                         const line = lines[i].trim();
@@ -84,12 +84,8 @@ img.pylogo {
                             }
                             let pkgName = line.substring(2, line.indexOf(".")).trim();
                             currentPatch = {name: pkgName, version: DB.ANY_VERSION};
-                        } else if (line.startsWith('#')) {
-                            if (!currentPatch.comment) {
-                                currentPatch.comment = line.substring(1).trim();
-                            } else {
-                                currentPatch.comment += ' ' + line.substring(1).trim();
-                            }
+                        } else if (line.startsWith('note =')) {
+                            currentPatch.comment = line.substring('note ='.length).trim();
                         } else if (line.startsWith('version =')) {
                             currentPatch.version = line.substring('version ='.length).trim().replace(/'|"/g, '').replace(/^== ?/, "").replace(/, ?/g, " and ");
                         } else if (line.startsWith('install-priority =')) {

graalpython/lib-graalpython/patches/metadata.toml

@@ -8,17 +8,16 @@ patch = 'autopep8.patch'
 license = 'MIT'
 
 [[bcrypt.rules]]
-# With pyo3 changes upstreamed, this patch is not needed in recent versions
-# This old version is still used in ray's tests
+note = "With pyo3 changes upstreamed, this patch is not needed in recent versions. This old version is still used in ray's tests."
 install-priority = 0
 version = '== 4.0.1'
 patch = 'bcrypt-4.0.1.patch'
 license = 'Apache-2.0'
 
 [[blosc2.rules]]
+note = "This patch is not needed in newer versions."
 version = '< 3'
 patch = 'blosc2.patch'
-# Not needed in newer versions
 install-priority = 0
 license = 'BSD-3-Clause'
 
@@ -54,7 +53,7 @@ license = 'BSD-3-Clause'
 [[cramjam.rules]]
 version = '== 2.7.0'
 patch = 'cramjam-2.7.0.patch'
-# Versions since 2.10 don't need a patch
+note = "Versions since 2.10 don't need a patch."
 install-priority = 0
 license = 'MIT'
 
@@ -106,6 +105,10 @@ version = '== 42.0.5'
 patch = 'cryptography-42.0.5.patch'
 license = 'Apache-2.0 OR BSD-3-Clause'
 
+[[cryptography.rules]]
+version = '>= 43.0.0'
+note = "Versions newer than 43 do not need a patch."
+
 [[Cython.rules]]
 version = '>= 3.0.10, <= 3.0.12'
 patch = 'Cython-3.0.10.patch'
@@ -201,7 +204,7 @@ version = '0.4.13'
 url = 'https://github.com/google/jax/archive/refs/tags/jaxlib-v0.4.13.tar.gz'
 
 [[jiter.rules]]
-# Upstreamed, should not be needed in the next release
+note = "Our patch was accepted upstream and should not be needed in the next release."
 version = '<= 0.5.0'
 install-priority = 0
 patch = 'jiter.patch'
@@ -289,16 +292,16 @@ version = '>= 4.9, < 5'
 patch = 'lxml-4.9.patch'
 license = 'BSD-3-Clause'
 
-# Patch already upstreamed, keeping it around for older versions
 [[MarkupSafe.rules]]
+note = "Our patch is upstreamed."
 version = "< 2.1.0"
 patch = "MarkupSafe.patch"
 license = "BSD-3-Clause"
 install-priority = 0  # Don't make pip install prefer this version
 dist-type = "sdist"
 
 [[meson-python.rules]]
-# Upstreamed
+note = "Our patch is upstreamed."
 version = '<= 0.16.0'
 install-priority = 0
 patch = 'meson-python.patch'
@@ -326,6 +329,7 @@ license = 'BSD-3-Clause'
 
 [[numba.rules]]
 # Not upstreamable, we disable the JIT
+note = "Numba JIT relies on bytecode parsing and is disabled on GraalPy."
 version = '== 0.59.1'
 patch = 'numba-0.59.1.patch'
 license = 'BSD-2-Clause'
@@ -391,11 +395,12 @@ version = '== 7.4.0'
 # Important: This patch esentially breaks the package, it's not upstreamable. The package relies on bytecode parsing
 # to do some otherwise impossible syntax shortcuts. Since it's esentially a type-checker, we just disable the overrides
 # checking altogether
+note = "This package relies on bytecode parsing and cannot work on GraalPy without significant changes. When installed on GraalPy, it is essentially disabled"
 patch = 'overrides-7.4.0.patch'
 license = 'Apache-2.0'
 
 [[packaging.rules]]
-# Merged upstream
+note = "Upstream packaging now supports GraalPy."
 version = '< 23.2'
 install-priority = 0
 patch = 'packaging.patch'
@@ -428,7 +433,7 @@ dist-type = 'sdist'
 [[pendulum.rules]]
 version = '== 3.0.0'
 patch = 'pendulum-3.0.0.patch'
-# Not needed since 3.1
+note = "Not needed since 3.1."
 install-priority = 0
 license = 'MIT'
 
@@ -510,7 +515,7 @@ patch = 'pyarrow-19.0.1.patch'
 license = 'Apache-2.0'
 
 [[pybind11.rules]]
-# Upstreamed
+note = "This patch was accepted upstream."
 install-priority = 0
 # Note: This patch is also inlined in torch
 version = '>= 2.11.0, <= 2.13.6'
@@ -559,7 +564,7 @@ license = 'MIT'
 [[PyDriller.rules]]
 version = '< 2.4'
 patch = 'PyDriller.patch'
-# Upstreamed
+note = "Our patch was accepted upstream."
 install-priority = 0
 license = 'Apache-2.0'
 
@@ -582,13 +587,14 @@ license = 'Apache-2.0'
 [[pymongo.rules]]
 version = ">= 4.8.0, <= 4.13.0"
 patch = 'pymongo-4.8.0.patch'
-# Upstreamed
+note = "Our patch was accepted upstream."
 install-priority = 0
 license = 'Apache-2.0'
 
 [[PyMuPDF.rules]]
 version = "== 1.25.4"
 patch = "pymupdf.patch"
+note = "Building PyMuPDF needs a CPython installation besides GraalPy on the PATH."
 # That project is AGPL, so do not actually include *any* code of pymupdf in the patch, not even an
 # empty line, in the diff context. The code we write in the patch is UPL - that is compatible with
 # AGPL in the sense that if someone were to apply it and distribute *that*, our patch is now part
@@ -683,14 +689,14 @@ version = '2.9.1'
 url = 'https://github.com/ray-project/ray/archive/refs/tags/ray-2.9.1.tar.gz'
 
 [[rpds_py.rules]]
-# Patch not needed anymore in recent version since pyo3 changes have been upstreamed
+note = "Our patch is not needed anymore in recent version since PyO3 now supports GraalPy."
 install-priority = 0
 version = '== 0.10.3'
 patch = 'rpds_py-0.10.3.patch'
 license = 'MIT'
 
 [[safetensors.rules]]
-# Recent versions should use pyo3 with upstream support for graalpy
+note = "Our patch is not needed anymore in recent version since PyO3 now supports GraalPy."
 install-priority = 0
 version = '== 0.3.3'
 patch = 'safetensors-0.3.3.patch'
@@ -863,11 +869,10 @@ license = 'PSF-2.0'
 subdir = 'src'
 
 [[urllib3.rules]]
-# urllib3 has a check that requires that the ssl implementation's name starts with "OpenSSL", we need to patch it out
+note = "urllib3 in this version range has a check that requires that the ssl implementation's name starts with 'OpenSSL', we need to patch it out. Older versions worked fine before the check was added. Newer versions turned it into a warning."
 patch = 'urllib3-2.patch'
 license = 'MIT'
 subdir = 'src'
-# Older versions worked fine before the check was added. Newer versions turned it into a warning
 version = '>= 2, < 2.0.3'
 install-priority = 0
 
@@ -879,7 +884,7 @@ license = 'MIT'
 [[watchfiles.rules]]
 version = '== 0.21.0'
 patch = 'watchfiles-0.21.0.patch'
-# Not needed in newer versions
+note = "Patch is not needed anymore in newer versions."
 install-priority = 0
 license = 'MIT'
 

mx.graalpython/verify_patches.py

@@ -60,7 +60,7 @@
 }
 
 SECTIONS = frozenset({'rules', 'add-sources'})
-RULE_KEYS = frozenset({'version', 'patch', 'license', 'subdir', 'dist-type', 'install-priority'})
+RULE_KEYS = frozenset({'version', 'patch', 'license', 'subdir', 'dist-type', 'install-priority', 'note'})
 
 
 def validate_metadata(patches_dir):