lang/python/doc/texinfo/maintenance-mode.texi

   1 \input texinfo    @c -*- texinfo -*-
   2 @c %**start of header
   3 @setfilename maintenance-mode.info
   4 @settitle Maintenance Mode
   5 @documentencoding utf-8
   6 @documentlanguage en
   7 @c %**end of header
   8
   9 @finalout
  10 @titlepage
  11 @title Maintenance Mode
  12 @author Ben McGinnes
  13 @end titlepage
  14
  15 @contents
  16
  17 @ifnottex
  18 @node Top
  19 @top Maintenance Mode
  20 @end ifnottex
  21
  22 @menu
  23 * Maintenance Mode from 2019::
  24
  25 @detailmenu
  26 --- The Detailed Node Listing ---
  27
  28 Maintenance Mode from 2019
  29
  30 * Maintainer from 2019 onward::
  31 * Using the Python Bindings from 2019 and beyond::
  32 * Documentation formats::
  33
  34 Documentation formats
  35
  36 * Cautionary Notes regarding Sphinx and EPUB::
  37
  38 @end detailmenu
  39 @end menu
  40
  41 @node Maintenance Mode from 2019
  42 @chapter Maintenance Mode from 2019
  43
  44 @multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
  45 @item Version:
  46 @tab 0.0.1
  47 @item GPGME Version:
  48 @tab 1.13.0
  49 @item Author:
  50 @tab Ben McGinnes <ben@@gnupg.org>
  51 @item Author GPG Key:
  52 @tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
  53 @item Language:
  54 @tab Australian English, British English
  55 @item xml:lang:
  56 @tab en-AU, en-GB, en
  57 @end multitable
  58
  59 From the beginning of 2019 the Python bindings to GPGME will enter
  60 maintenance mode, meaning that new features will not be added and only
  61 bug fixes and security fixes will be made.  This also means that
  62 documentation beyond that existing at the end of 2018 will not be
  63 developed further except to correct errors.
  64
  65 Though use of these bindings appears to have been quite well received,
  66 there has been no indication of what demand there is, if any for
  67 either financial backing of the current Python bindings development or
  68 support contracts with g10code GmbH citing the necessity of including
  69 the bindings.
  70
  71 @menu
  72 * Maintainer from 2019 onward::
  73 * Using the Python Bindings from 2019 and beyond::
  74 * Documentation formats::
  75 @end menu
  76
  77 @node Maintainer from 2019 onward
  78 @section Maintainer from 2019 onward
  79
  80 How does this affect the position of GnuPG Python Bindings Maintainer?
  81
  82 Well, I will remain as maintainer of the bindings; but without funding
  83 for that position, the amount of time I will be able to dedicate
  84 solely to this task will be limited and reduced to volunteered time.
  85 As with all volunteered time and effort in free software projects,
  86 this will be subject to numerous external imperatives.
  87
  88 @node Using the Python Bindings from 2019 and beyond
  89 @section Using the Python Bindings from 2019 and beyond
  90
  91 For most, if not all, Python developers using these bindings; they
  92 will continue to “just work” the same as they always have.  Expansions
  93 of GPGME itself are usually handled by SWIG with the existing code and
  94 thus bindings are generated properly when the bindings are installed
  95 alongside GPGME and when the latter is built from source.
  96
  97 In the rare circumstances where that is not enough to address some new
  98 addition to GPGME, then that is a bug and thus subject to the
  99 maintenance mode provisions (i.e. it will be fixed following a bug
 100 report being raised and your humble author will need to remember where
 101 the timesheet template was filed, depending on how many years off such
 102 an event is).
 103
 104 All the GPGME functionality will continue to be accessible via the
 105 lower level, dynamically generated methods which match the GPGME C
 106 documentation.  While the more intuitively Pythonic higher level layer
 107 already covers the vast majority of functionality people require with
 108 key generation, signatures, certifications (key signing), encryption,
 109 decryption, verification, validation, trust levels and so on.
 110
 111 Any wanted features lacking in the Python bindings are usually lacking
 112 because they are missing from GPGME itself (e.g. revoking keys via the
 113 API) and in such cases they are usually deliberately excluded.  More
 114 discussion of these issues can be found in the archives of the
 115 @uref{https://lists.gnupg.org/mailman/listinfo/gnupg-devel, gnupg-devel mailing list}.
 116
 117 Any features existing in the dynamically generated layer for which
 118 people want a specific, higher level function included to make it more
 119 Pythonic (e.g. to avoid needing to learn or memorise cryptographic
 120 mode values or GnuPG status code numbers), would be a feature request
 121 and @emph{not} a bug.
 122
 123 It is still worthwhile requesting it, but the addition of such a
 124 feature would not be guaranteed and provided on a purely volunteer
 125 basis.  Expediting such a request would require funding that request.
 126
 127 Those with a commercial interest in expediting such a feature request
 128 already know how to @uref{https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset, expedite it} (use the message field to state what
 129 feature is being requested).
 130
 131 @node Documentation formats
 132 @section Documentation formats
 133
 134 The documentation has been written in Org mode for GNU Emacs, with
 135 both Texinfo and reStructuredText formats generated from that.  The
 136 Texinfo files are intended for use with the rest of the GnuPG
 137 documentation; while the reStructuredText files are intended for use
 138 with Docutils and Sphinx, as with other Python projects.
 139
 140 @menu
 141 * Cautionary Notes regarding Sphinx and EPUB::
 142 @end menu
 143
 144 @node Cautionary Notes regarding Sphinx and EPUB
 145 @subsection Cautionary Notes regarding Sphinx and EPUB
 146
 147 Though Python's Docutils in conjunction with Sphinx is capable of
 148 generating some very useful HTML sites, as proven by @uref{https://readthedocs.org/, Read the Docs} and
 149 the @uref{https://docs.python.org/, Python documentation}, there are a number of output formats it does
 150 not handle well.  At the top of the list of things it manages to break
 151 so atrociously as to be embarassing is the @uref{http://idpf.org/epub, EPUB 3} format.
 152
 153 The automatically generated EPUB of the CPython documentation always
 154 contains hundreds of validation errors and even the modest amount of
 155 documentation here @uref{https://files.au.adversary.org.s3.amazonaws.com/crypto/gpgme-python/rst/epub/GPGMEPythonBindings.epub, produced a file} with approximately thirty
 156 validation errors.  As the volume of documentation content increases,
 157 so does the induced errors.  Whereas Texinfo doesn't produce EPUB
 158 output at all, nor does Org-mode.
 159
 160 Should there ever be genuine demand for this format, lodge a @uref{https://dev.gnupg.org/maniphest/task/edit/form/4/, feature
 161 request} case marked for @uref{https://dev.gnupg.org/p/BenM/, my} attention.  The means of generating such
 162 files flawlessly is already available, but is not yet part of the
 163 GnuPG build system.  Nor is it integrated with a means of converting
 164 Org mode input files to the relevant base format automatically, as can
 165 already be done when converting Org to reStructuredText or Org to
 166 Texinfo.  As a certain amount of work would be required to get it
 167 done, there would need to be clear demand for that work to be done.
 168
 169 @bye