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