diff options
Diffstat (limited to 'lang/python/doc/src/maintenance-mode.org')
| -rw-r--r-- | lang/python/doc/src/maintenance-mode.org | 135 |
1 files changed, 0 insertions, 135 deletions
diff --git a/lang/python/doc/src/maintenance-mode.org b/lang/python/doc/src/maintenance-mode.org deleted file mode 100644 index 4b4e0fca..00000000 --- a/lang/python/doc/src/maintenance-mode.org +++ /dev/null @@ -1,135 +0,0 @@ -# -*- mode: org -*- -#+TITLE: Maintenance Mode -#+AUTHOR: Ben McGinnes -#+LATEX_COMPILER: xelatex -#+LATEX_CLASS: article -#+LATEX_CLASS_OPTIONS: [12pt] -#+LATEX_HEADER: \usepackage{xltxtra} -#+LATEX_HEADER: \usepackage[margin=1in]{geometry} -#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Times New Roman} -#+LATEX_HEADER: \author{Ben McGinnes <[email protected]>} - - -* Maintenance Mode from 2019 - :PROPERTIES: - :CUSTOM_ID: maintenance-mode - :END: - -| Version: | 0.0.1 | -| GPGME Version: | 1.13.0 | -| Author: | Ben McGinnes <[email protected]> | -| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D | -| Language: | Australian English, British English | -| xml:lang: | en-AU, en-GB, en | - -From the beginning of 2019 the Python bindings to GPGME will enter -maintenance mode, meaning that new features will not be added and only -bug fixes and security fixes will be made. This also means that -documentation beyond that existing at the end of 2018 will not be -developed further except to correct errors. - -Though use of these bindings appears to have been quite well received, -there has been no indication of what demand there is, if any for -either financial backing of the current Python bindings development or -support contracts with g10code GmbH citing the necessity of including -the bindings. - - -** Maintainer from 2019 onward - :PROPERTIES: - :CUSTOM_ID: maintenance-mode-bm - :END: - -How does this affect the position of GnuPG Python Bindings Maintainer? - -Well, I will remain as maintainer of the bindings; but without funding -for that position, the amount of time I will be able to dedicate -solely to this task will be limited and reduced to volunteered time. -As with all volunteered time and effort in free software projects, -this will be subject to numerous external imperatives. - - -** Using the Python Bindings from 2019 and beyond - :PROPERTIES: - :CUSTOM_ID: maintenance-mode-blade-runner - :END: - -For most, if not all, Python developers using these bindings; they -will continue to “just work” the same as they always have. Expansions -of GPGME itself are usually handled by SWIG with the existing code and -thus bindings are generated properly when the bindings are installed -alongside GPGME and when the latter is built from source. - -In the rare circumstances where that is not enough to address some new -addition to GPGME, then that is a bug and thus subject to the -maintenance mode provisions (i.e. it will be fixed following a bug -report being raised and your humble author will need to remember where -the timesheet template was filed, depending on how many years off such -an event is). - -All the GPGME functionality will continue to be accessible via the -lower level, dynamically generated methods which match the GPGME C -documentation. While the more intuitively Pythonic higher level layer -already covers the vast majority of functionality people require with -key generation, signatures, certifications (key signing), encryption, -decryption, verification, validation, trust levels and so on. - -Any wanted features lacking in the Python bindings are usually lacking -because they are missing from GPGME itself (e.g. revoking keys via the -API) and in such cases they are usually deliberately excluded. More -discussion of these issues can be found in the archives of the -[[https://lists.gnupg.org/mailman/listinfo/gnupg-devel][gnupg-devel mailing list]]. - -Any features existing in the dynamically generated layer for which -people want a specific, higher level function included to make it more -Pythonic (e.g. to avoid needing to learn or memorise cryptographic -mode values or GnuPG status code numbers), would be a feature request -and /not/ a bug. - -It is still worthwhile requesting it, but the addition of such a -feature would not be guaranteed and provided on a purely volunteer -basis. Expediting such a request would require funding that request. - -Those with a commercial interest in expediting such a feature request -already know how to [[https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset][expedite it]] (use the message field to state what -feature is being requested). - - -** Documentation formats - :PROPERTIES: - :CUSTOM_ID: docs - :END: - -The documentation has been written in Org mode for GNU Emacs, with -both Texinfo and reStructuredText formats generated from that. The -Texinfo files are intended for use with the rest of the GnuPG -documentation; while the reStructuredText files are intended for use -with Docutils and Sphinx, as with other Python projects. - - -*** Cautionary Notes regarding Sphinx and EPUB - :PROPERTIES: - :CUSTOM_ID: sphinx-made-epubs-suck - :END: - -Though Python's Docutils in conjunction with Sphinx is capable of -generating some very useful HTML sites, as proven by [[https://readthedocs.org/][Read the Docs]] and -the [[https://docs.python.org/][Python documentation]], there are a number of output formats it does -not handle well. At the top of the list of things it manages to break -so atrociously as to be embarassing is the [[http://idpf.org/epub][EPUB 3]] format. - -The automatically generated EPUB of the CPython documentation always -contains hundreds of validation errors and even the modest amount of -documentation here [[https://files.au.adversary.org.s3.amazonaws.com/crypto/gpgme-python/rst/epub/GPGMEPythonBindings.epub][produced a file]] with approximately thirty -validation errors. As the volume of documentation content increases, -so does the induced errors. Whereas Texinfo doesn't produce EPUB -output at all, nor does Org-mode. - -Should there ever be genuine demand for this format, lodge a [[https://dev.gnupg.org/maniphest/task/edit/form/4/][feature -request]] case marked for [[https://dev.gnupg.org/p/BenM/][my]] attention. The means of generating such -files flawlessly is already available, but is not yet part of the -GnuPG build system. Nor is it integrated with a means of converting -Org mode input files to the relevant base format automatically, as can -already be done when converting Org to reStructuredText or Org to -Texinfo. As a certain amount of work would be required to get it -done, there would need to be clear demand for that work to be done. |