From b841d434e5c011396b3fd49503eb3b88236cc3cf Mon Sep 17 00:00:00 2001
From: Athanasius <github@miggy.org>
Date: Sun, 28 Mar 2021 12:01:05 +0100
Subject: [PATCH] plugintest: Document core version code & add to PLUGINS.md

* New PLUGINS.md section 'Checking core EDMC version'.
* And the same comments might as well be in the plugintest/load.py.
---
 PLUGINS.md                       | 34 ++++++++++++++++++++++++++++++++
 docs/examples/plugintest/load.py |  9 ++++++---
 2 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/PLUGINS.md b/PLUGINS.md
index 9ccd0df6..d80e1e66 100644
--- a/PLUGINS.md
+++ b/PLUGINS.md
@@ -170,6 +170,40 @@ functions, in the output.
 
 ---
 
+### Checking core EDMC version
+
+If you have code that needs to act differently under different versions of 
+this application then you can check the core version using:
+
+```python
+import semantic_version
+from config import appversion
+
+...
+    if isinstance(appversion, str):
+        core_version = appversion  # Up until 5.0.0-beta1 this is a string
+
+    elif callable(appversion):
+        core_version = appversion()  # From 5.0.0-beta1 it's a function
+
+    else:
+        core_version = '<UNKNOWN!>'  # Paranoia
+
+    # Either way you now have a string
+    logger.info(f'Core EDMC version: {core_version}')
+    # The easiest way to compare is using semantic_version, so convert
+    core_version_sv = semantic_version.Version(core_version)
+    # And then compare like this
+    if core_version_sv < semantic_version.Version('5.0.0-beta1'):
+        logger.info('EDMC core version is before 5.0.0-beta1')
+
+    else:
+        logger.info('EDMC core version is at least 5.0.0-beta1')
+
+```
+
+---
+
 ### Startup
 
 EDMC will import the `load.py` file as a module and then call the
diff --git a/docs/examples/plugintest/load.py b/docs/examples/plugintest/load.py
index b64a0cb8..c5eedd88 100644
--- a/docs/examples/plugintest/load.py
+++ b/docs/examples/plugintest/load.py
@@ -94,16 +94,19 @@ def plugin_start3(plugin_dir: str) -> str:
     :return: 'Pretty' name of this plugin.
     """
     if isinstance(appversion, str):
-        core_version = appversion
+        core_version = appversion  # Up until 5.0.0-beta1 this is a string
 
     elif callable(appversion):
-        core_version = appversion()
+        core_version = appversion()  # From 5.0.0-beta1 it's a function
 
     else:
-        core_version = '<UNKNOWN!>'
+        core_version = '<UNKNOWN!>'  # Paranoia
 
+    # Either way you now have a string
     logger.info(f'Core EDMC version: {core_version}')
+    # The easiest way to compare is using semantic_version, so convert
     core_version_sv = semantic_version.Version(core_version)
+    # And then compare like this
     if core_version_sv < semantic_version.Version('5.0.0-beta1'):
         logger.info('EDMC core version is before 5.0.0-beta1')