Short History

* Fixed or updated the most fundamental errors.
* Also included some details on which modules are available on PyPI,
  as well as what happened to the PyME commit log.

1 files changed, 96 insertions, 20 deletions

diff --git a/lang/python/docs/Short_History.org b/lang/python/docs/Short_History.org
index 2295499c..e0cd877e 100644
--- a/lang/python/docs/Short_History.org
+++ b/lang/python/docs/Short_History.org
@@ -50,13 +50,30 @@ return to the source.  This is a short explanation of that journey.
 
    In 2015 Ben McGinnes approached Martin about a Python 3 version,
    while investigating how complex a task this would be the task ended
-   up being completed.  A subsequent discussion with Werner Koch led to
-   the decision to fold the Python 3 port back into the original GPGME
-   release in the languages subdirectory for non-C bindings.  Ben is
-   the maintainer of the Python 3 port within GPGME.
+   up being completed.  A subsequent discussion with Werner Koch led
+   to the decision to fold the Python 3 port back into the original
+   GPGME release in the languages subdirectory for non-C bindings
+   under the module name of =pyme3=.
 
-   In 2016 PyME was renamed to "gpg" and adopted by the upstream GnuPG
-   team.
+   In 2016 this PyME module was integrated back into the GPGME project
+   by Justus Winter.  During the course of this work Justus adjusted
+   the port to restore limited support for Python 2, but not as many
+   minor point releases as the original PyME package supports.  During
+   the course of this integration the package was renamed to more
+   accurately reflect its status as a component of GPGME.  The =pyme3=
+   module was renamed to =gpg= and adopted by the upstream GnuPG team.
+
+   In 2017 Justus departed G10code and the GnuPG team.  Following this
+   Ben returned to maintain of gpgme Python bindings and continue
+   building them from that point.
+
+* Relics of the past
+  :PROPERTIES:
+  :CUSTOM_ID: relics-past
+  :END:
+
+There are a few things, in addition to code specific factors, such as
+SWIG itself, which are worth noting here.
 
 ** The Annoyances of Git
    :PROPERTIES:
@@ -65,23 +82,82 @@ return to the source.  This is a short explanation of that journey.
 
    As anyone who has ever worked with git knows, submodules are
    horrible way to deal with pretty much anything.  In the interests
-   of avoiding migraines, that is being skipped with addition of PyME
-   to GPGME.  Instead the files will be added to the subdirectory,
-   along with a copy of the entire git log up to that point as a
-   separate file within the docs directory (old-commits.log).  As the
-   log for PyME is nearly 100KB and the log for GPGME is approximately
-   1MB, this would cause considerable bloat, as well as some
-   confusion, should the two be merged.  Hence the unfortunate, but
-   necessary, step to simply move the files.  A regular repository
-   version will be maintained should it be possible to implement this
-   better in the future.
+   of avoiding migraines, that was skipped with addition of the PyME
+   code to GPGME.
+
+   Instead the files were added to a subdirectory of the =lang/=
+   directory, along with a copy of the entire git log up to that point
+   as a separate file within the =lang/python/docs/= directory.[fn:1]
+   As the log for PyME is nearly 100KB and the log for GPGME is
+   approximately 1MB, this would cause considerable bloat, as well as
+   some confusion, should the two be merged.
+
+   Hence the unfortunate, but necessary, step to simply move the
+   files.  A regular repository version has been maintained should it
+   be possible to implement this better in the future.
 
 ** The Perils of PyPI
    :PROPERTIES:
    :CUSTOM_ID: the-perils-of-pypi
    :END:
 
-   At the current time the Python 3 fork is not available via PyPI and
-   the pip installer.  The recommended installation method is to follow
-   the instructions in lang/py3-pyme/INSTALL.  This will build the
-   necessary SWIG portions against the installed version of GPGME.
+   The early port of the Python 2 =pyme= module as =pyme3= was never
+   added to PyPI while the focus remained on development and testing
+   during 2015 and early 2016.  Later in 2016, however, when Justus
+   completed his major integration work and subsequently renamed the
+   module from =pyme3= to =gpg=, some prior releases were also
+   provided through PyPI.
+
+   Since these bindings require a matching release of the GPGME
+   libraries in order to function, it was determined that there was
+   little benefit in also providing a copy through PyPI since anyone
+   obtaining the GPGME source code would obtain the Python bindings
+   source code at the same time.  Whereas there was the potential to
+   sew confusion amongst Python users installing the module from PyPI,
+   only to discover that without the relevant C files, header files or
+   SWIG compiled binaries, the Python module did them little good.
+
+   There are only two files on PyPI which might turn up in a search
+   for this module or a sample of its content:
+
+   1. gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library
+   2. pyme (0.9.0) - Python support for GPGME GnuPG cryptography library
+
+*** GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library
+    :PROPERTIES:
+    :CUSTOM_ID: pypi-gpgme-180
+    :END:
+
+    This is the most recent version to reach PyPI and is the version
+    of the official Pyhon bindings which shipped with GPGME 1.8.0.  If
+    you have GPGME 1.8.0 installed and /only/ 1.8.0 installed, then it
+    is probably safe to use this copy from PyPI.
+
+    As there have been a lot of changes since the release of GPGME
+    1.8.0, the GnuPG Project recommends not using this version of the
+    module and instead installing the current version of GPGME along
+    with the Python bindings included with that package.
+
+*** PyME 0.9.0 - Python support for GPGME GnuPG cryptography library
+    :PROPERTIES:
+    :CUSTOM_ID: pypi-gpgme-90
+    :END:
+
+    This is the last release of the PyME bindings maintained by Martin
+    Albrecht and is only compatible with Python 2, it will not work
+    with Python 3.  This is the version of the software from which the
+    port from Python 2 to Python 3 code was made in 2015.
+
+    Users of the more recent Python bindings will recognise numerous
+    points of similarity, but also significant differences.  It is
+    likely that the more recent official bindings will feel "more
+    pythonic."
+
+    For those using Python 2, there is essentially no harm in using
+    this module, but it may lack a number of more recent features
+    added to GPGME.
+
+* Footnotes
+
+[fn:1] The entire PyME git log and other preceding VCS logs are
+located in the =gpgme/lanf/python/docs/old-commits.log= file.