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

   1 \input texinfo
   2
   3 @setfilename gnus-coding
   4 @settitle Gnus Coding Style and Maintainance Guide
   5 @syncodeindex fn cp
   6 @syncodeindex vr cp
   7 @syncodeindex pg cp
   8
   9 @copying
  10 Copyright (c) 2004  Free Software Foundation, Inc.
  11
  12 @quotation
  13 Permission is granted to copy, distribute and/or modify this document
  14 under the terms of the GNU Free Documentation License, Version 1.1 or
  15 any later version published by the Free Software Foundation; with no
  16 Invariant Sections, with the Front-Cover texts being ``A GNU
  17 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
  18 license is included in the section entitled ``GNU Free Documentation
  19 License'' in the Emacs manual.
  20
  21 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
  22 this GNU Manual, like GNU software.  Copies published by the Free
  23 Software Foundation raise funds for GNU development.''
  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 Maintainance Guide
  35
  36 @c @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 CVS
  42 @c anyway hoping that it might annoy someone enough to fix it.  ;-)
  43 @c Fixing only a paragraph also is appreciated.
  44
  45 @node Top
  46
  47 @section Gnus Coding Style
  48 @subsection Dependencies
  49
  50 @c message / gnus
  51 @c
  52 @c nn*
  53 @c
  54 @c mm*
  55 @c
  56 @c rfc*
  57 @c
  58 @c tla netrc pop3 dig dns ...
  59 @c format-spec.el
  60
  61 @subsection Compatibility
  62
  63 @c Compatibility with XEmacs and older Emacs versions in v5-10 and in the
  64 @c trunk.
  65
  66 @c @table
  67 @c x
  68 @c @end table
  69
  70 @section Gnus Maintainance Guide
  71
  72 @subsection Stable and development versions
  73
  74 The CVS trunk is developed quite actively.
  75
  76 @c Most of the time Gnus is developed on the trunk.
  77
  78 @c Exeption: several month of feature freeze after a release,
  79 @c e.g. 5.10.1
  80
  81
  82 @subsection Syncing
  83
  84 @c Some MIDs related to this follow.  Use http://thread.gmane.org/MID
  85 @c (and click on the subject) to get the thread on Gmane.
  86
  87 @c Some quotes from Miles Bader follow...
  88
  89 @c <v9eklyke6b.fsf@marauder.physik.uni-ulm.de>
  90 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
  91
  92 I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to
  93 require more manual work.
  94
  95 By default I sync about once a week.  I also try to follow any Gnus
  96 threads on the mailing lists and make sure any changes being discussed
  97 are kept more up-to-date (so say 1-2 days delay for "topical" changes).
  98
  99
 100 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
 101
 102 BTW, just to add even more verbose explanation about the syncing thing:
 103
 104 Basically my idea is that the Emacs-Gnus gateway will cause all common
 105 files in Emacs and Gnus v5-10 to be identical except when there's a very
 106 good reason (e.g., the Gnus version string in Emacs says "5.11", but the
 107 v5-10 version string remains "5.10.whatever").  Furthermore, all changes
 108 in these files in either Emacs or the v5-10 branch will be installed
 109 into the Gnus CVS trunk, again except where there's a good reason
 110 (typically so far the only exception has been that the changes already
 111 exist in the trunk in modified form).  Because of this, when the next
 112 Emacs Gnus upgrade comes, it should be very easy -- just plonk in the
 113 files from the Gnus trunk without worrying about lost changes from the
 114 Emacs tree.
 115
 116 The effect of this is that as hacker, you should generally only have to
 117 make changes in one place:
 118
 119   1) If it's a file which is thought of as being outside of Gnus (e.g.,
 120      the new "encrypt.el"), you should probably make the change in the
 121      Emacs tree, and it will show up in the Gnus tree a few days later.
 122
 123      If you don't have Emacs CVS access (or it's inconvenient), you can
 124      change such a file in the v5-10 branch, and it should propagate to
 125      Emacs CVS -- however, it will get some extra scrutiny (by me) to see
 126      if the changes are possibly controversial and need discussion on the
 127      mailing list.  [Many changes are obvious bug-fixes however, so often
 128      there won't be any problem.]
 129
 130   2) If it's to a Gnus file, and it's important enough that it should be
 131      part of Emacs/v5-10, then you can make the change on the v5-10
 132      branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few
 133      days later).
 134
 135      If you know that there will be conflicts (perhaps because the
 136      affected source code is different in v5-10 and the Gnus CVS trunk),
 137      then you can install your change in both places, and when I try to
 138      sync them, there will be a conflict -- however, since in most such
 139      cases there would be a conflict _anyway_, it's often easier for me
 140      to resolve it simply if I see two "identical" changes, and can just
 141      choose the proper one, rather than having to actually fix the code.
 142
 143   3) For general Gnus development changes, of course you just make the
 144      change on the Gnus CVS trunk and it goes into Emacs a few years
 145      later... :-)
 146
 147 Of course in any case, if you just can't wait for me to sync your
 148 change, you can commit it in more than one place and probably there will
 149 be no problem; usually the changes are textually identical anyway, so
 150 can be easily resolved automatically (sometimes I notice silly things in
 151 such multiple commits, like whitespace differences, and unify those ;-).
 152
 153
 154 @subsection Miscellanea
 155
 156 Starting from No Gnus, the @file{GNUS-NEWS} is created from
 157 @file{texi/gnus-news.texi}.  Don't edit @file{GNUS-NEWS}.  Edit
 158 @file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the
 159 @file{texi} directory and commit @file{GNUS-NEWS} and
 160 @file{texi/gnus-news.texi}.
 161
 162
 163 @c Local Variables:
 164 @c mode: texinfo
 165 @c coding: iso-8859-1
 166 @c End:
 167
 168 @ignore
 169    arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931
 170 @end ignore