1 files changed, 152 insertions, 0 deletions
diff --git a/lang/python/doc/rst/short-history.rst b/lang/python/doc/rst/short-history.rst
new file mode 100644
index 0000000..8cf604f
--- /dev/null
+++ b/lang/python/doc/rst/short-history.rst
@@ -0,0 +1,152 @@
+Overview
+========
+
+The GPGME Python bindings passed through many hands and numerous phases
+before, after a fifteen year journey, coming full circle to return to
+the source. This is a short explanation of that journey.
+
+.. _in-the-begining:
+
+In the beginning
+----------------
+
+In 2002 John Goerzen released PyME; Python bindings for the GPGME module
+which utilised the current release of Python of the time and SWIG. [1]_
+Shortly after creating it and ensuring it worked he stopped supporting
+it, though he left his work available on his Gopher site.
+
+Keeping the flame alive
+-----------------------
+
+A couple of years later the project was picked up by Igor Belyi and
+actively developed and maintained by him from 2004 to 2008. Igor's
+whereabouts at the time of this document's creation are unknown, but the
+current authors do hope he is well. We're assuming (or hoping) that life
+did what life does and made continuing untenable.
+
+Passing the torch
+-----------------
+
+In 2014 Martin Albrecht wanted to patch a bug in the PyME code and
+discovered the absence of Igor. Following a discussion on the PyME
+mailing list he became the new maintainer for PyME, releasing version
+0.9.0 in May of that year. He remains the maintainer of the original
+PyME release in Python 2.6 and 2.7 (available via PyPI).
+
+.. _ouroboros:
+
+Coming full circle
+------------------
+
+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 under the module name of
+``pyme3``.
+
+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-past:
+
+Relics of the past
+==================
+
+There are a few things, in addition to code specific factors, such as
+SWIG itself, which are worth noting here.
+
+The Annoyances of Git
+---------------------
+
+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 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. [2]_ 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
+------------------
+
+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:
+
+#. gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library
+#. pyme (0.9.0) - Python support for GPGME GnuPG cryptography library
+
+.. _pypi-gpgme-180:
+
+GPG 1·8·0 - Python bindings for GPGME GnuPG cryptography library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+.. _pypi-gpgme-90:
+
+PyME 0·9·0 - Python support for GPGME GnuPG cryptography library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+=========
+
+.. [1]
+   In all likelihood thos would have been Python 2.2 or possibly Python
+   2.3.
+
+.. [2]
+   The entire PyME git log and other preceding VCS logs are located in
+   the ``gpgme/lang/python/docs/old-commits.log`` file.