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