3 @setfilename gnus-coding
4 @settitle Gnus Coding Style and Maintainance Guide
10 Copyright (c) 2004, 2005, 2007 Free Software Foundation, Inc.
13 Permission is granted to copy, distribute and/or modify this document
14 under the terms of the GNU Free Documentation License, Version 1.1 or
15 any later version published by the Free Software Foundation; with no
16 Invariant Sections, with the Front-Cover texts being ``A GNU
17 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
18 license is included in the section entitled ``GNU Free Documentation
19 License'' in the Emacs manual.
21 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
22 this GNU Manual, like GNU software. Copies published by the Free
23 Software Foundation raise funds for GNU development.''
25 This document is part of a collection distributed under the GNU Free
26 Documentation License. If you want to distribute this document
27 separately from the collection, you can do so by adding a copy of the
28 license to the document, as described in section 6 of the license.
34 @title Gnus Coding Style and Maintainance Guide
36 @author by Reiner Steib <Reiner.Steib@@gmx.de>
41 @c Obviously this is only a very rudimentary draft. We put it in CVS
42 @c anyway hoping that it might annoy someone enough to fix it. ;-)
43 @c Fixing only a paragraph also is appreciated.
46 @top Gnus Coding Style and Maintainance Guide
47 This manual describes @dots{}
49 * Gnus Coding Style:: Gnus Coding Style
50 * Gnus Maintainance Guide:: Gnus Maintainance Guide
53 @c @ref{Gnus Reference Guide, ,Gnus Reference Guide, gnus, The Gnus Newsreader}
55 @node Gnus Coding Style
56 @chapter Gnus Coding Style
59 The Gnus distribution contains a lot of libraries that have been written
60 for Gnus and used intensively for Gnus. But many of those libraries are
61 useful on their own. E.g. other Emacs Lisp packages might use the
62 @acronym{MIME} library @xref{Top, ,Top, emacs-mime, The Emacs MIME
65 @subsection General purpose libraries
70 @file{.netrc} parsing functionality.
71 @c As of 2005-10-21...
72 There are no Gnus dependencies in this file.
75 Functions for formatting arbitrary formatting strings.
76 @c As of 2005-10-21...
77 There are no Gnus dependencies in this file.
81 @subsection Encryption and security
85 File encryption routines
86 @c As of 2005-10-25...
87 There are no Gnus dependencies in this file.
90 Read passwords from user, possibly using a password cache.
91 @c As of 2005-10-21...
92 There are no Gnus dependencies in this file.
95 TLS/SSL support via wrapper around GnuTLS
96 @c As of 2005-10-21...
97 There are no Gnus dependencies in this file.
100 Glue for the various PGP implementations.
101 @c As of 2005-10-21...
102 There are no Gnus dependencies in these files.
105 SHA1 Secure Hash Algorithm.
106 @c As of 2007-08-25...
107 There are no Gnus dependencies in these files.
110 Functions to encode/decode hexadecimal string.
111 @c As of 2007-08-25...
112 There are no Gnus dependencies in these files.
115 @subsection Networking
119 Domain Name System dig interface.
120 @c As of 2005-10-21...
121 There are no serious Gnus dependencies in this file. Uses
122 @code{gnus-run-mode-hooks} (a wrapper function).
124 @item dns.el, dns-mode.el
125 Domain Name Service lookups.
126 @c As of 2005-10-21...
127 There are no Gnus dependencies in these files.
130 @subsection Mail and News related RFCs
134 Post Office Protocol (RFC 1460) interface.
135 @c As of 2005-10-21...
136 There are no Gnus dependencies in this file.
139 @acronym{IMAP} library.
140 @c As of 2005-10-21...
141 There are no Gnus dependencies in this file.
144 Functions for parsing RFC822bis headers.
145 @c As of 2005-10-21...
146 There are no Gnus dependencies in this file.
149 HZ (rfc1843) decoding. HZ is a data format for exchanging files of
150 arbitrarily mixed Chinese and @acronym{ASCII} characters.
151 @c As of 2005-10-21...
152 @code{rfc1843-gnus-setup} seem to be useful only for Gnus. Maybe this
153 function should be relocated to remove dependencies on Gnus. Other
154 minor dependencies: @code{gnus-newsgroup-name} could be eliminated by
155 using an optional argument to @code{rfc1843-decode-article-body}.
158 Functions for decoding rfc2045 headers
159 @c As of 2007-08-25...
160 There are no Gnus dependencies in these files.
163 Functions for encoding and decoding rfc2047 messages
164 @c As of 2007-08-25...
165 There are no Gnus dependencies in these files.
167 Only a couple of tests for gnusy symbols.
170 RFC2104 Hashed Message Authentication Codes
171 @c As of 2007-08-25...
172 There are no Gnus dependencies in these files.
175 Functions for decoding rfc2231 headers
176 @c As of 2007-08-25...
177 There are no Gnus dependencies in these files.
180 Interpret RFC2646 "flowed" text.
181 @c As of 2005-10-27...
182 There are no Gnus dependencies in this file.
185 Elisp native uudecode.
186 @c As of 2005-12-06...
187 There are no Gnus dependencies in this file.
188 @c ... but the custom group is gnus-extract.
191 Functions for Cancel-Lock feature
192 @c Cf. draft-ietf-usefor-cancel-lock-01.txt
193 @c Although this draft has expired, Canlock-Lock revived in 2007 when
194 @c major news providers (e.g. news.individual.org) started to use it.
195 @c As of 2007-08-25...
196 There are no Gnus dependencies in these files.
202 All message composition from Gnus (both mail and news) takes place in
203 Message mode buffers. Message mode is intended to be a replacement for
204 Emacs mail mode. There should be no Gnus dependencies in
207 @subsection Emacs @acronym{MIME}
209 The files @file{mml*.el} and @file{mm-*.el} provide @acronym{MIME}
210 functionality for Emacs.
212 @acronym{MML} (@acronym{MIME} Meta Language) is supposed to be
213 independent from Gnus. Alas it is not anymore. Patches and suggestions
214 to remove the dependencies are welcome.
216 @subsection Gnus backends
218 The files @file{nn*.el} provide functionality for accessing NNTP
219 (@file{nntp.el}), IMAP (@file{nnimap.el}) and several other Mail back
220 ends (probably @file{nnml.el}, @file{nnfolder.el} and
221 @file{nnmaildir.el} are the most widely used mail back ends).
223 @c mm-uu requires nnheader which requires gnus-util. message.el also
224 @c requires nnheader.
227 @section Compatibility
229 No Gnus and Gnus 5.10.10 and up should work on:
237 Gnus 5.10.8 and below should work on:
245 @node Gnus Maintainance Guide
246 @chapter Gnus Maintainance Guide
248 @section Stable and development versions
250 The development of Gnus normally is done on the CVS trunk, i.e. there
251 are no separate branches to develop and test new features. Most of the
252 time, the trunk is developed quite actively with more or less daily
253 changes. Only after a new major release, e.g. 5.10.1, there's usually a
254 feature period of several months. After the release of Gnus 5.10.6 the
255 development of new features started again on the trunk while the 5.10
256 series is continued on the stable branch (v5-10) from which more stable
257 releases will be done when needed (5.10.7, @dots{}).
258 @ref{Gnus Development, ,Gnus Development, gnus, The Gnus Newsreader}
260 Stable releases of Gnus finally become part of Emacs. E.g. Gnus 5.8
261 became a part of Emacs 21 (relabeled to Gnus 5.9). The 5.10 series
262 became part of Emacs 22 as Gnus 5.11.
266 @c Some MIDs related to this follow. Use http://thread.gmane.org/MID
267 @c (and click on the subject) to get the thread on Gmane.
269 @c Some quotes from Miles Bader follow...
271 @c <v9eklyke6b.fsf@marauder.physik.uni-ulm.de>
272 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
274 In the past, the inclusion of Gnus into Emacs was quite cumbersome. For
275 each change made to Gnus in Emacs repository, it had to be checked that
276 it was applied to the new Gnus version, too. Else, bug fixes done in
277 Emacs repository might have been lost.
279 With the inclusion of Gnus 5.10, Miles Bader has set up an Emacs-Gnus
280 gateway to ensure the bug fixes from Emacs CVS are propagated to Gnus
281 CVS semi-automatically. These bug fixes are installed on the stable
282 branch and on the trunk. Basically the idea is that the gateway will
283 cause all common files in Emacs and Gnus v5-10 to be identical except
284 when there's a very good reason (e.g., the Gnus version string in Emacs
285 says @samp{5.11}, but the v5-10 version string remains @samp{5.10.x}).
286 Furthermore, all changes in these files in either Emacs or the v5-10
287 branch will be installed into the Gnus CVS trunk, again except where
288 there's a good reason.
289 @c (typically so far the only exception has been that the changes
290 @c already exist in the trunk in modified form).
291 Because of this, when the next major version of Gnus will be included in
292 Emacs, it should be very easy -- just plonk in the files from the Gnus
293 trunk without worrying about lost changes from the Emacs tree.
295 The effect of this is that as hacker, you should generally only have to
296 make changes in one place:
300 If it's a file which is thought of as being outside of Gnus (e.g., the
301 new @file{encrypt.el}), you should probably make the change in the Emacs
302 tree, and it will show up in the Gnus tree a few days later.
304 If you don't have Emacs CVS access (or it's inconvenient), you can
305 change such a file in the v5-10 branch, and it should propagate to Emacs
306 CVS -- however, it will get some extra scrutiny (by Miles) to see if the
307 changes are possibly controversial and need discussion on the mailing
308 list. Many changes are obvious bug-fixes however, so often there won't
312 If it's to a Gnus file, and it's important enough that it should be part
313 of Emacs and the v5-10 branch, then you can make the change on the v5-10
314 branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few days
315 later). The most prominent examples for such changes are bug-fixed
316 including improvements on the documentation.
318 If you know that there will be conflicts (perhaps because the affected
319 source code is different in v5-10 and the Gnus CVS trunk), then you can
320 install your change in both places, and when I try to sync them, there
321 will be a conflict -- however, since in most such cases there would be a
322 conflict @emph{anyway}, it's often easier for me to resolve it simply if
323 I see two @samp{identical} changes, and can just choose the proper one,
324 rather than having to actually fix the code.
327 For general Gnus development changes, of course you just make the
328 change on the Gnus CVS trunk and it goes into Emacs a few years
332 Of course in any case, if you just can't wait for me to sync your
333 change, you can commit it in more than one place and probably there will
334 be no problem; usually the changes are textually identical anyway, so
335 can be easily resolved automatically (sometimes I notice silly things in
336 such multiple commits, like whitespace differences, and unify those ;-).
339 @c I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to
340 @c require more manual work.
342 @c By default I sync about once a week. I also try to follow any Gnus
343 @c threads on the mailing lists and make sure any changes being discussed
344 @c are kept more up-to-date (so say 1-2 days delay for "topical" changes).
346 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
348 @c BTW, just to add even more verbose explanation about the syncing thing:
352 @heading @file{GNUS-NEWS}
354 Starting from No Gnus, the @file{GNUS-NEWS} is created from
355 @file{texi/gnus-news.texi}. Don't edit @file{GNUS-NEWS}. Edit
356 @file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the
357 @file{texi} directory and commit @file{GNUS-NEWS} and
358 @file{texi/gnus-news.texi}.
360 @heading Conventions for version information in defcustoms
362 For new customizable variables introduced in Oort Gnus (including the
363 v5-10 branch) use @code{:version "22.1" ;; Oort Gnus} (including the
364 comment) or e.g. @code{:version "22.2" ;; Gnus 5.10.10} if the feature
365 was added for Emacs 22.2 and Gnus 5.10.10.
367 If the variable is new in No Gnus use @code{:version "23.0" ;; No Gnus}.
369 The same applies for customizable variables when its default value was
374 @c coding: iso-8859-1
378 arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931