diff options
Diffstat (limited to 'lang/python/doc/texinfo/maintenance-mode.texi')
| -rw-r--r-- | lang/python/doc/texinfo/maintenance-mode.texi | 169 |
1 files changed, 0 insertions, 169 deletions
diff --git a/lang/python/doc/texinfo/maintenance-mode.texi b/lang/python/doc/texinfo/maintenance-mode.texi deleted file mode 100644 index 92457190..00000000 --- a/lang/python/doc/texinfo/maintenance-mode.texi +++ /dev/null @@ -1,169 +0,0 @@ -\input texinfo @c -*- texinfo -*- -@c %**start of header -@setfilename maintenance-mode.info -@settitle Maintenance Mode -@documentencoding utf-8 -@documentlanguage en -@c %**end of header - -@finalout -@titlepage -@title Maintenance Mode -@author Ben McGinnes -@end titlepage - -@contents - -@ifnottex -@node Top -@top Maintenance Mode -@end ifnottex - -@menu -* Maintenance Mode from 2019:: - -@detailmenu ---- The Detailed Node Listing --- - -Maintenance Mode from 2019 - -* Maintainer from 2019 onward:: -* Using the Python Bindings from 2019 and beyond:: -* Documentation formats:: - -Documentation formats - -* Cautionary Notes regarding Sphinx and EPUB:: - -@end detailmenu -@end menu - -@node Maintenance Mode from 2019 -@chapter Maintenance Mode from 2019 - -@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} -@item Version: -@tab 0.0.1 -@item GPGME Version: -@tab 1.13.0 -@item Author: -@tab Ben McGinnes <ben@@gnupg.org> -@item Author GPG Key: -@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D -@item Language: -@tab Australian English, British English -@item xml:lang: -@tab en-AU, en-GB, en -@end multitable - -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. - -@menu -* Maintainer from 2019 onward:: -* Using the Python Bindings from 2019 and beyond:: -* Documentation formats:: -@end menu - -@node Maintainer from 2019 onward -@section Maintainer from 2019 onward - -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. - -@node Using the Python Bindings from 2019 and beyond -@section Using the Python Bindings from 2019 and beyond - -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 -@uref{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 @emph{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 @uref{https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset, expedite it} (use the message field to state what -feature is being requested). - -@node Documentation formats -@section Documentation formats - -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. - -@menu -* Cautionary Notes regarding Sphinx and EPUB:: -@end menu - -@node Cautionary Notes regarding Sphinx and EPUB -@subsection Cautionary Notes regarding Sphinx and EPUB - -Though Python's Docutils in conjunction with Sphinx is capable of -generating some very useful HTML sites, as proven by @uref{https://readthedocs.org/, Read the Docs} and -the @uref{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 @uref{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 @uref{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 @uref{https://dev.gnupg.org/maniphest/task/edit/form/4/, feature -request} case marked for @uref{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. - -@bye
\ No newline at end of file |