Add notes on adding a new OpenSSL version

python · encukou · Nov 28, 2024 · Nov 26, 2024 · Nov 27, 2024 · Nov 27, 2024
commit 7ebe9aacab6685d19dbb40342b93e9157b731d5d
@@ -251,6 +251,7 @@ jobs:
       matrix:
         os: [ubuntu-24.04]
         openssl_ver: [3.0.15, 3.1.7, 3.2.3, 3.3.2]
+        # See Tools/ssl/make_ssl_data.py for notes on adding a new version
     env:
       OPENSSL_VER: ${{ matrix.openssl_ver }}
       MULTISSL_DIR: ${{ github.workspace }}/multissl

@@ -120,6 +120,7 @@ static void _PySSLFixErrno(void) {
 #endif
 
 /* Include generated data (error codes) */
+/* See make_ssl_data.h for notes on adding a new version. */
 #if (OPENSSL_VERSION_NUMBER >= 0x30100000L)
 #include "_ssl_data_31.h"
 #elif (OPENSSL_VERSION_NUMBER >= 0x30000000L)

@@ -8,6 +8,25 @@
 - the path to the OpenSSL git checkout
 - the path to the header file to be generated Modules/_ssl_data_{version}.h
 - error codes are version specific
+
+The OpenSSL git checkout should be at a specific tag, using commands like:
+    git tag --list 'openssl-*'
+    git switch --detach openssl-3.4.0
+
+
+After generating the definitions, the result with newest pre-existing file.
+You can use a command like:
+
+    git diff --no-index Modules/_ssl_data_31.h Modules/_ssl_data_34.h
+
+- If the new version *only* adds new definitions, remove the pre-existing file
+  and adjust the #include in _ssl.c to point to the new version.
+- If the new version removes or renumbers some definitions, keep both files and
+  add a new #include in _ssl.c.
+
+A newly supported OpenSSL version should alsko be added to:
+- Tools/ssl/multissltests.py
+- .github/workflows/build.yml
 """
 
 import argparse

@@ -51,6 +51,7 @@
     "3.1.7",
     "3.2.3",
     "3.3.2",
+    # See make_ssl_data.py for notes on adding a new version.
 ]
 
 LIBRESSL_OLD_VERSIONS = [