9377bbb263aad80cd2558d5877a4ebaa09f5608f
[gpgme.git] / 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