doc/misc/gnus-coding.texi

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