Commit | Line | Data |
---|---|---|
01c52d31 MB |
1 | \input texinfo |
2 | ||
29993416 | 3 | @setfilename gnus-coding.info |
cd1181db | 4 | @settitle Gnus Coding Style and Maintenance Guide |
c6ab4664 | 5 | @documentencoding UTF-8 |
01c52d31 MB |
6 | @syncodeindex fn cp |
7 | @syncodeindex vr cp | |
8 | @syncodeindex pg cp | |
9 | ||
10 | @copying | |
6bc383b1 | 11 | Copyright @copyright{} 2004--2005, 2007--2014 Free Software |
5dc584b5 | 12 | Foundation, Inc. |
01c52d31 MB |
13 | |
14 | @quotation | |
15 | Permission is granted to copy, distribute and/or modify this document | |
6a2c4aec | 16 | under the terms of the GNU Free Documentation License, Version 1.3 or |
01c52d31 | 17 | any later version published by the Free Software Foundation; with no |
551a89e1 | 18 | Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', |
0b1af106 GM |
19 | and with the Back-Cover Texts as in (a) below. A copy of the license |
20 | is included in the section entitled ``GNU Free Documentation License''. | |
01c52d31 | 21 | |
6f093307 | 22 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
6bf430d1 | 23 | modify this GNU manual.'' |
01c52d31 MB |
24 | @end quotation |
25 | @end copying | |
26 | ||
27 | ||
28 | @titlepage | |
bff3818b | 29 | @title Gnus Coding Style and Maintenance Guide |
01c52d31 MB |
30 | |
31 | @author by Reiner Steib <Reiner.Steib@@gmx.de> | |
32 | ||
33 | @insertcopying | |
34 | @end titlepage | |
35 | ||
bff3818b KY |
36 | @c Obviously this is only a very rudimentary draft. We put it in the |
37 | @c repository anyway hoping that it might annoy someone enough to fix | |
38 | @c it. ;-) Fixing only a paragraph also is appreciated. | |
01c52d31 | 39 | |
5dc584b5 | 40 | @ifnottex |
01c52d31 | 41 | @node Top |
cd1181db | 42 | @top Gnus Coding Style and Maintenance Guide |
01c52d31 | 43 | This manual describes @dots{} |
5dc584b5 | 44 | |
1df7defd | 45 | @insertcopying |
5dc584b5 KB |
46 | @end ifnottex |
47 | ||
01c52d31 MB |
48 | @menu |
49 | * Gnus Coding Style:: Gnus Coding Style | |
cd1181db | 50 | * Gnus Maintenance Guide:: Gnus Maintenance Guide |
0b1af106 | 51 | * GNU Free Documentation License:: The license for this documentation. |
01c52d31 MB |
52 | @end menu |
53 | ||
54 | @c @ref{Gnus Reference Guide, ,Gnus Reference Guide, gnus, The Gnus Newsreader} | |
55 | ||
56 | @node Gnus Coding Style | |
57 | @chapter Gnus Coding Style | |
58 | @section Dependencies | |
59 | ||
60 | The Gnus distribution contains a lot of libraries that have been written | |
61 | for Gnus and used intensively for Gnus. But many of those libraries are | |
1df7defd | 62 | useful on their own. E.g., other Emacs Lisp packages might use the |
01c52d31 MB |
63 | @acronym{MIME} library @xref{Top, ,Top, emacs-mime, The Emacs MIME |
64 | Manual}. | |
65 | ||
66 | @subsection General purpose libraries | |
67 | ||
68 | @table @file | |
69 | ||
70 | @item netrc.el | |
71 | @file{.netrc} parsing functionality. | |
72 | @c As of 2005-10-21... | |
73 | There are no Gnus dependencies in this file. | |
74 | ||
75 | @item format-spec.el | |
76 | Functions for formatting arbitrary formatting strings. | |
77 | @c As of 2005-10-21... | |
78 | There are no Gnus dependencies in this file. | |
79 | ||
80 | @item hex-util.el | |
81 | Functions to encode/decode hexadecimal string. | |
82 | @c As of 2007-08-25... | |
83 | There are no Gnus dependencies in these files. | |
84 | @end table | |
85 | ||
86 | @subsection Encryption and security | |
87 | ||
88 | @table @file | |
89 | @item encrypt.el | |
90 | File encryption routines | |
91 | @c As of 2005-10-25... | |
92 | There are no Gnus dependencies in this file. | |
93 | ||
94 | @item password.el | |
95 | Read passwords from user, possibly using a password cache. | |
96 | @c As of 2005-10-21... | |
97 | There are no Gnus dependencies in this file. | |
98 | ||
99 | @item tls.el | |
100 | TLS/SSL support via wrapper around GnuTLS | |
101 | @c As of 2005-10-21... | |
102 | There are no Gnus dependencies in this file. | |
103 | ||
104 | @item pgg*.el | |
105 | Glue for the various PGP implementations. | |
106 | @c As of 2005-10-21... | |
107 | There are no Gnus dependencies in these files. | |
108 | ||
109 | @item sha1.el | |
110 | SHA1 Secure Hash Algorithm. | |
111 | @c As of 2007-08-25... | |
112 | There are no Gnus dependencies in these files. | |
113 | @end table | |
114 | ||
115 | @subsection Networking | |
116 | ||
117 | @table @file | |
118 | @item dig.el | |
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). | |
123 | ||
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. | |
128 | @end table | |
129 | ||
130 | @subsection Mail and News related RFCs | |
131 | ||
132 | @table @file | |
133 | @item pop3.el | |
134 | Post Office Protocol (RFC 1460) interface. | |
135 | @c As of 2005-10-21... | |
136 | There are no Gnus dependencies in this file. | |
137 | ||
138 | @item imap.el | |
139 | @acronym{IMAP} library. | |
140 | @c As of 2005-10-21... | |
141 | There are no Gnus dependencies in this file. | |
142 | ||
143 | @item ietf-drums.el | |
144 | Functions for parsing RFC822bis headers. | |
145 | @c As of 2005-10-21... | |
146 | There are no Gnus dependencies in this file. | |
147 | ||
148 | @item rfc1843.el | |
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}. | |
156 | ||
157 | @item rfc2045.el | |
158 | Functions for decoding rfc2045 headers | |
159 | @c As of 2007-08-25... | |
160 | There are no Gnus dependencies in these files. | |
161 | ||
162 | @item rfc2047.el | |
163 | Functions for encoding and decoding rfc2047 messages | |
164 | @c As of 2007-08-25... | |
165 | There are no Gnus dependencies in these files. | |
166 | @c | |
167 | Only a couple of tests for gnusy symbols. | |
168 | ||
169 | @item rfc2104.el | |
170 | RFC2104 Hashed Message Authentication Codes | |
171 | @c As of 2007-08-25... | |
172 | There are no Gnus dependencies in these files. | |
173 | ||
174 | @item rfc2231.el | |
175 | Functions for decoding rfc2231 headers | |
176 | @c As of 2007-08-25... | |
177 | There are no Gnus dependencies in these files. | |
178 | ||
179 | @item flow-fill.el | |
180 | Interpret RFC2646 "flowed" text. | |
181 | @c As of 2005-10-27... | |
182 | There are no Gnus dependencies in this file. | |
183 | ||
184 | @item uudecode.el | |
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. | |
189 | ||
190 | @item canlock.el | |
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 | |
1df7defd | 194 | @c major news providers (e.g., news.individual.org) started to use it. |
01c52d31 MB |
195 | @c As of 2007-08-25... |
196 | There are no Gnus dependencies in these files. | |
197 | ||
198 | @end table | |
199 | ||
200 | @subsection message | |
201 | ||
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 | |
205 | @file{message.el}. Alas it is not anymore. Patches and suggestions to | |
206 | remove the dependencies are welcome. | |
207 | ||
208 | @c message.el requires nnheader which requires gnus-util. | |
209 | ||
210 | @subsection Emacs @acronym{MIME} | |
211 | ||
212 | The files @file{mml*.el} and @file{mm-*.el} provide @acronym{MIME} | |
213 | functionality for Emacs. | |
214 | ||
215 | @acronym{MML} (@acronym{MIME} Meta Language) is supposed to be | |
216 | independent from Gnus. Alas it is not anymore. Patches and suggestions | |
217 | to remove the dependencies are welcome. | |
218 | ||
219 | @subsection Gnus backends | |
220 | ||
221 | The files @file{nn*.el} provide functionality for accessing NNTP | |
222 | (@file{nntp.el}), IMAP (@file{nnimap.el}) and several other Mail back | |
223 | ends (probably @file{nnml.el}, @file{nnfolder.el} and | |
224 | @file{nnmaildir.el} are the most widely used mail back ends). | |
225 | ||
226 | @c mm-uu requires nnheader which requires gnus-util. message.el also | |
227 | @c requires nnheader. | |
228 | ||
229 | ||
230 | @section Compatibility | |
231 | ||
232 | No Gnus and Gnus 5.10.10 and up should work on: | |
233 | @itemize @bullet | |
234 | @item | |
235 | Emacs 21.1 and up. | |
236 | @item | |
237 | XEmacs 21.4 and up. | |
238 | @end itemize | |
239 | ||
240 | Gnus 5.10.8 and below should work on: | |
241 | @itemize @bullet | |
242 | @item | |
243 | Emacs 20.7 and up. | |
244 | @item | |
245 | XEmacs 21.1 and up. | |
246 | @end itemize | |
247 | ||
cd1181db JB |
248 | @node Gnus Maintenance Guide |
249 | @chapter Gnus Maintenance Guide | |
01c52d31 MB |
250 | |
251 | @section Stable and development versions | |
252 | ||
bff3818b KY |
253 | The development of Gnus normally is done on the Git repository trunk |
254 | as of April 19, 2010 (formerly it was done in CVS; the repository is | |
1df7defd | 255 | at http://git.gnus.org), i.e., there are no separate branches to |
bff3818b KY |
256 | develop and test new features. Most of the time, the trunk is |
257 | developed quite actively with more or less daily changes. Only after | |
1df7defd | 258 | a new major release, e.g., 5.10.1, there's usually a feature period of |
bff3818b KY |
259 | several months. After the release of Gnus 5.10.6 the development of |
260 | new features started again on the trunk while the 5.10 series is | |
261 | continued on the stable branch (v5-10) from which more stable releases | |
262 | will be done when needed (5.10.8, @dots{}). @ref{Gnus Development, | |
263 | ,Gnus Development, gnus, The Gnus Newsreader} | |
01c52d31 | 264 | |
1df7defd PE |
265 | Stable releases of Gnus finally become part of Emacs. E.g., Gnus 5.8 |
266 | became a part of Emacs 21 (relabeled to Gnus 5.9). The 5.10 series | |
01c52d31 MB |
267 | became part of Emacs 22 as Gnus 5.11. |
268 | ||
269 | @section Syncing | |
270 | ||
271 | @c Some MIDs related to this follow. Use http://thread.gmane.org/MID | |
272 | @c (and click on the subject) to get the thread on Gmane. | |
273 | ||
274 | @c Some quotes from Miles Bader follow... | |
275 | ||
276 | @c <v9eklyke6b.fsf@marauder.physik.uni-ulm.de> | |
277 | @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp> | |
278 | ||
279 | In the past, the inclusion of Gnus into Emacs was quite cumbersome. For | |
280 | each change made to Gnus in Emacs repository, it had to be checked that | |
281 | it was applied to the new Gnus version, too. Else, bug fixes done in | |
282 | Emacs repository might have been lost. | |
283 | ||
284 | With the inclusion of Gnus 5.10, Miles Bader has set up an Emacs-Gnus | |
285 | gateway to ensure the bug fixes from Emacs CVS are propagated to Gnus | |
7cad71ad G |
286 | CVS semi-automatically. |
287 | ||
288 | After Emacs moved to bzr and Gnus moved to git, Katsumi Yamaoka has | |
289 | taken over the chore of keeping Emacs and Gnus in sync. In general, | |
290 | changes made to one repository will usually be replicated in the other | |
291 | within a few days. | |
292 | ||
293 | Basically the idea is that the gateway will cause all common files in | |
294 | Emacs and Gnus v5-13 to be identical except when there's a very good | |
295 | reason (e.g., the Gnus version string in Emacs says @samp{5.11}, but | |
296 | the v5-13 version string remains @samp{5.13.x}). Furthermore, all | |
297 | changes in these files in either Emacs or the v5-13 branch will be | |
298 | installed into the Gnus git trunk, again except where there's a good | |
299 | reason. | |
300 | ||
01c52d31 MB |
301 | @c (typically so far the only exception has been that the changes |
302 | @c already exist in the trunk in modified form). | |
303 | Because of this, when the next major version of Gnus will be included in | |
f99f1641 | 304 | Emacs, it should be very easy---just plonk in the files from the Gnus |
01c52d31 MB |
305 | trunk without worrying about lost changes from the Emacs tree. |
306 | ||
307 | The effect of this is that as hacker, you should generally only have to | |
308 | make changes in one place: | |
309 | ||
310 | @itemize | |
311 | @item | |
312 | If it's a file which is thought of as being outside of Gnus (e.g., the | |
313 | new @file{encrypt.el}), you should probably make the change in the Emacs | |
314 | tree, and it will show up in the Gnus tree a few days later. | |
315 | ||
7cad71ad | 316 | If you don't have Emacs bzr access (or it's inconvenient), you can |
01c52d31 | 317 | change such a file in the v5-10 branch, and it should propagate to Emacs |
f99f1641 | 318 | bzr---however, it will get some extra scrutiny (by Miles) to see if the |
01c52d31 MB |
319 | changes are possibly controversial and need discussion on the mailing |
320 | list. Many changes are obvious bug-fixes however, so often there won't | |
321 | be any problem. | |
322 | ||
323 | @item | |
324 | If it's to a Gnus file, and it's important enough that it should be part | |
325 | of Emacs and the v5-10 branch, then you can make the change on the v5-10 | |
7cad71ad | 326 | branch, and it will go into Emacs bzr and the Gnus git trunk (a few days |
01c52d31 MB |
327 | later). The most prominent examples for such changes are bug-fixed |
328 | including improvements on the documentation. | |
329 | ||
330 | If you know that there will be conflicts (perhaps because the affected | |
7cad71ad | 331 | source code is different in v5-10 and the Gnus git trunk), then you can |
01c52d31 | 332 | install your change in both places, and when I try to sync them, there |
f99f1641 | 333 | will be a conflict---however, since in most such cases there would be a |
01c52d31 MB |
334 | conflict @emph{anyway}, it's often easier for me to resolve it simply if |
335 | I see two @samp{identical} changes, and can just choose the proper one, | |
336 | rather than having to actually fix the code. | |
337 | ||
338 | @item | |
339 | For general Gnus development changes, of course you just make the | |
bff3818b | 340 | change on the Gnus Git trunk and it goes into Emacs a few years |
01c52d31 | 341 | later... :-) |
bff3818b | 342 | |
01c52d31 MB |
343 | @end itemize |
344 | ||
345 | Of course in any case, if you just can't wait for me to sync your | |
346 | change, you can commit it in more than one place and probably there will | |
347 | be no problem; usually the changes are textually identical anyway, so | |
348 | can be easily resolved automatically (sometimes I notice silly things in | |
349 | such multiple commits, like whitespace differences, and unify those ;-). | |
350 | ||
351 | ||
352 | @c I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to | |
353 | @c require more manual work. | |
354 | ||
355 | @c By default I sync about once a week. I also try to follow any Gnus | |
356 | @c threads on the mailing lists and make sure any changes being discussed | |
357 | @c are kept more up-to-date (so say 1-2 days delay for "topical" changes). | |
358 | ||
359 | @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp> | |
360 | ||
361 | @c BTW, just to add even more verbose explanation about the syncing thing: | |
362 | ||
363 | @section Miscellanea | |
364 | ||
365 | @heading @file{GNUS-NEWS} | |
366 | ||
367 | Starting from No Gnus, the @file{GNUS-NEWS} is created from | |
368 | @file{texi/gnus-news.texi}. Don't edit @file{GNUS-NEWS}. Edit | |
369 | @file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the | |
370 | @file{texi} directory and commit @file{GNUS-NEWS} and | |
371 | @file{texi/gnus-news.texi}. | |
372 | ||
373 | @heading Conventions for version information in defcustoms | |
374 | ||
375 | For new customizable variables introduced in Oort Gnus (including the | |
376 | v5-10 branch) use @code{:version "22.1" ;; Oort Gnus} (including the | |
1df7defd | 377 | comment) or, e.g., @code{:version "22.2" ;; Gnus 5.10.10} if the feature |
01c52d31 MB |
378 | was added for Emacs 22.2 and Gnus 5.10.10. |
379 | @c | |
8f7abae3 | 380 | If the variable is new in No Gnus use @code{:version "23.1" ;; No Gnus}. |
01c52d31 MB |
381 | |
382 | The same applies for customizable variables when its default value was | |
383 | changed. | |
384 | ||
0b1af106 GM |
385 | @node GNU Free Documentation License |
386 | @appendix GNU Free Documentation License | |
387 | @include doclicense.texi | |
388 | ||
01c52d31 MB |
389 | @c Local Variables: |
390 | @c mode: texinfo | |
86c86abf | 391 | @c coding: utf-8 |
01c52d31 | 392 | @c End: |