\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