cgit.sxemacs.org Git - gnus/blob - texi/gnus-coding.texi

   1 \input texinfo
   2
   3 @setfilename gnus-coding.info
   4 @settitle Gnus Coding Style and Maintenance Guide
   5 @include docstyle.texi
   6 @syncodeindex fn cp
   7 @syncodeindex vr cp
   8 @syncodeindex pg cp
   9
  10 @copying
  11 Copyright @copyright{} 2004--2005, 2007--2015 Free Software
  12 Foundation, Inc.
  13
  14 @quotation
  15 Permission is granted to copy, distribute and/or modify this document
  16 under the terms of the GNU Free Documentation License, Version 1.3 or
  17 any later version published by the Free Software Foundation; with no
  18 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
  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''.
  21
  22 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  23 modify this GNU manual.''
  24 @end quotation
  25 @end copying
  26
  27
  28 @titlepage
  29 @title Gnus Coding Style and Maintenance Guide
  30
  31 @author by Reiner Steib  <Reiner.Steib@@gmx.de>
  32
  33 @insertcopying
  34 @end titlepage
  35
  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.
  39
  40 @ifnottex
  41 @node Top
  42 @top Gnus Coding Style and Maintenance Guide
  43 This manual describes @dots{}
  44
  45 @insertcopying
  46 @end ifnottex
  47
  48 @menu
  49 * Gnus Coding Style:: Gnus Coding Style
  50 * Gnus Maintenance Guide:: Gnus Maintenance Guide
  51 * GNU Free Documentation License::  The license for this documentation.
  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
  62 useful on their own.  E.g., other Emacs Lisp packages might use the
  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
 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.
 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
 248 @node Gnus Maintenance Guide
 249 @chapter Gnus Maintenance Guide
 250
 251 @section Stable and development versions
 252
 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
 255 at http://git.gnus.org), i.e., there are no separate branches to
 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
 258 a new major release, e.g., 5.10.1, there's usually a feature period of
 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}
 264
 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
 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
 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
 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
 304 Emacs, it should be very easy---just plonk in the files from the Gnus
 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
 316 If you don't have Emacs repository access (or it's inconvenient), you
 317 can change such a file in the v5-10 branch, and it should propagate to
 318 the Emacs repository---however, it will get some extra scrutiny (by
 319 Miles) to see if the changes are possibly controversial and need
 320 discussion on the mailing list.  Many changes are obvious bug-fixes
 321 however, so often there won't 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
 326 branch, and it will go into Emacs and the Gnus git trunk (a few days
 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
 331 source code is different in v5-10 and the Gnus git trunk), then you can
 332 install your change in both places, and when I try to sync them, there
 333 will be a conflict---however, since in most such cases there would be a
 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
 340 change on the Gnus Git trunk and it goes into Emacs a few years
 341 later... :-)
 342
 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
 377 comment) or, e.g., @code{:version "22.2" ;; Gnus 5.10.10} if the feature
 378 was added for Emacs 22.2 and Gnus 5.10.10.
 379 @c
 380 If the variable is new in No Gnus use @code{:version "23.1" ;; No Gnus}.
 381
 382 The same applies for customizable variables when its default value was
 383 changed.
 384
 385 @node GNU Free Documentation License
 386 @appendix GNU Free Documentation License
 387 @include doclicense.texi
 388
 389 @c Local Variables:
 390 @c mode: texinfo
 391 @c coding: utf-8
 392 @c End: