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