gh-127330: Update for OpenSSL 3.4 & document+improve the update process (GH-127331)

- Add `git describe` output to headers generated by `make_ssl_data.py`

  This info is more important than the date when the file was generated.
  It does mean that the tool now requires a Git checkout of OpenSSL,
  not for example a release tarball.

- Regenerate the older file to add the info.
  To the other older file, add a note about manual edits.

- Add notes on how to add a new OpenSSL version

- Add 3.4 error messages and multissl tests

3 files changed, 34 insertions, 6 deletions

diff --git a/Tools/c-analyzer/cpython/_parser.py b/Tools/c-analyzer/cpython/_parser.py
index 21be53e..a08b32f 100644
--- a/Tools/c-analyzer/cpython/_parser.py
+++ b/Tools/c-analyzer/cpython/_parser.py
@@ -70,9 +70,7 @@ Python/thread_pthread.h
 Python/thread_pthread_stubs.h
 
 # only huge constants (safe but parsing is slow)
-Modules/_ssl_data_31.h
-Modules/_ssl_data_300.h
-Modules/_ssl_data_111.h
+Modules/_ssl_data_*.h
 Modules/cjkcodecs/mappings_*.h
 Modules/unicodedata_db.h
 Modules/unicodename_db.h
diff --git a/Tools/ssl/make_ssl_data.py b/Tools/ssl/make_ssl_data.py
index d24e022..da05d2b 100755
--- a/Tools/ssl/make_ssl_data.py
+++ b/Tools/ssl/make_ssl_data.py
@@ -5,9 +5,28 @@ This script should be called *manually* when we want to upgrade SSLError
 `library` and `reason` mnemonics to a more recent OpenSSL version.
 
 It takes two arguments:
-- the path to the OpenSSL source tree (e.g. git checkout)
+- 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, compare 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 also be added to:
+- Tools/ssl/multissltests.py
+- .github/workflows/build.yml
 """
 
 import argparse
@@ -15,6 +34,7 @@ import datetime
 import operator
 import os
 import re
+import subprocess
 
 
 parser = argparse.ArgumentParser(
@@ -117,9 +137,17 @@ def main():
     # sort by libname, numeric error code
     args.reasons = sorted(reasons, key=operator.itemgetter(0, 3))
 
+    git_describe = subprocess.run(
+        ['git', 'describe', '--long', '--dirty'],
+        cwd=args.srcdir,
+        capture_output=True,
+        encoding='utf-8',
+        check=True,
+        )
     lines = [
-        "/* File generated by Tools/ssl/make_ssl_data.py */"
-        f"/* Generated on {datetime.datetime.utcnow().isoformat()} */"
+        "/* File generated by Tools/ssl/make_ssl_data.py */",
+        f"/* Generated on {datetime.datetime.now(datetime.UTC).isoformat()} */",
+        f"/* Generated from Git commit {git_describe.stdout.strip()} */",
     ]
     lines.extend(gen_library_codes(args))
     lines.append("")
diff --git a/Tools/ssl/multissltests.py b/Tools/ssl/multissltests.py
index eae0e0c..2cd0c39 100755
--- a/Tools/ssl/multissltests.py
+++ b/Tools/ssl/multissltests.py
@@ -51,6 +51,8 @@ OPENSSL_RECENT_VERSIONS = [
     "3.1.7",
     "3.2.3",
     "3.3.2",
+    "3.4.0",
+    # See make_ssl_data.py for notes on adding a new version.
 ]
 
 LIBRESSL_OLD_VERSIONS = [