3 @setfilename gnus-coding
4 @settitle Gnus Coding Style and Maintainance Guide
10 Copyright (c) 2004 Free Software Foundation, Inc.
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.
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.''
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.
34 @title Gnus Coding Style and Maintainance Guide
43 @section Gnus Coding Style
44 @subsection Dependencies
54 @c tla netrc pop3 dig dns ...
57 @subsection Compatibility
59 @c Compatibility with XEmacs and older Emacs versions in v5-10 and in the
66 @section Gnus Maintainance Guide
68 @subsection Stable and development versions
70 The CVS trunk is developed quite actively.
72 @c Most of the time Gnus is developed on the trunk.
74 @c Exeption: several month of feature freeze after a release,
80 @c <v9eklyke6b.fsf@marauder.physik.uni-ulm.de>
81 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
83 I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to
84 require more manual work.
86 By default I sync about once a week. I also try to follow any Gnus
87 threads on the mailing lists and make sure any changes being discussed
88 are kept more up-to-date (so say 1-2 days delay for "topical" changes).
91 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
93 BTW, just to add even more verbose explanation about the syncing thing:
95 Basically my idea is that the Emacs-Gnus gateway will cause all common
96 files in Emacs and Gnus v5-10 to be identical except when there's a very
97 good reason (e.g., the Gnus version string in Emacs says "5.11", but the
98 v5-10 version string remains "5.10.whatever"). Furthermore, all changes
99 in these files in either Emacs or the v5-10 branch will be installed
100 into the Gnus CVS trunk, again except where there's a good reason
101 (typically so far the only exception has been that the changes already
102 exist in the trunk in modified form). Because of this, when the next
103 Emacs Gnus upgrade comes, it should be very easy -- just plonk in the
104 files from the Gnus trunk without worrying about lost changes from the
107 The effect of this is that as hacker, you should generally only have to
108 make changes in one place:
110 1) If it's a file which is thought of as being outside of Gnus (e.g.,
111 the new "encrypt.el"), you should probably make the change in the
112 Emacs tree, and it will show up in the Gnus tree a few days later.
114 If you don't have Emacs CVS access (or it's inconvenient), you can
115 change such a file in the v5-10 branch, and it should propagate to
116 Emacs CVS -- however, it will get some extra scrutiny (by me) to see
117 if the changes are possibly controversial and need discussion on the
118 mailing list. [Many changes are obvious bug-fixes however, so often
119 there won't be any problem.]
121 2) If it's to a Gnus file, and it's important enough that it should be
122 part of Emacs/v5-10, then you can make the change on the v5-10
123 branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few
126 If you know that there will be conflicts (perhaps because the
127 affected source code is different in v5-10 and the Gnus CVS trunk),
128 then you can install your change in both places, and when I try to
129 sync them, there will be a conflict -- however, since in most such
130 cases there would be a conflict _anyway_, it's often easier for me
131 to resolve it simply if I see two "identical" changes, and can just
132 choose the proper one, rather than having to actually fix the code.
134 3) For general Gnus development changes, of course you just make the
135 change on the Gnus CVS trunk and it goes into Emacs a few years
138 Of course in any case, if you just can't wait for me to sync your
139 change, you can commit it in more than one place and probably there will
140 be no problem; usually the changes are textually identical anyway, so
141 can be easily resolved automatically (sometimes I notice silly things in
142 such multiple commits, like whitespace differences, and unify those ;-).
145 @subsection Miscellanea
147 Starting from No Gnus, the @file{GNUS-NEWS} is created from
148 @file{texi/gnus-news.texi}. Don't edit @file{GNUS-NEWS}. Edit
149 @file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the
150 @file{texi} directory and commit @file{GNUS-NEWS} and
151 @file{texi/gnus-news.texi}.
156 @c coding: iso-8859-1