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, 135 insertions, 0 deletions
diff --git a/lang/python/doc/src/maintenance-mode.org b/lang/python/doc/src/maintenance-mode.org new file mode 100644 index 00000000..4b4e0fca --- /dev/null +++ b/lang/python/doc/src/maintenance-mode.org @@ -0,0 +1,135 @@ +# -*- 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. |