1 files changed, 31 insertions, 3 deletions
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("")