Copyright (c) 2004, 2005  Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License'' in the Emacs manual.

     (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify this GNU Manual, like GNU software.  Copies published by the Free Software Foundation raise funds for GNU development.''

     This document is part of a collection distributed under the GNU Free Documentation License.  If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.

Gnus Coding Style and Maintainance Guide
****************************************

This manual describes ...

Gnus Coding Style
*****************

Dependencies
============

The Gnus distribution contains a lot of libraries that have been written for Gnus and used intensively for Gnus.  But many of those libraries are useful on their own.  E.g. other Emacs Lisp packages might use the MIME library see The Emacs MIME Manual.

General purpose libraries
-------------------------

netrc.el
     .netrc parsing functionality. There are no Gnus dependencies in this file.

format-spec.el
     Functions for formatting arbitrary formatting strings. There are no Gnus dependencies in this file.

Encryption and security
-----------------------

encrypt.el
     File encryption routines There are no Gnus dependencies in this file.

password.el
     Read passwords from user, possibly using a password cache. There are no Gnus dependencies in this file.

tls.el
     TLS/SSL support via wrapper around GnuTLS There are no Gnus dependencies in this file.

pgg*.el
     Glue for the various PGP implementations. There are no Gnus dependencies in these files.

Networking
----------

dig.el
     Domain Name System dig interface. There are no serious Gnus dependencies in this file.  Uses gnus-run-mode-hooks (a wrapper function).

dns*.el
     Domain Name Service lookups. There are no Gnus dependencies in these files.

Mail and News related RFCs
--------------------------

pop3.el
     Post Office Protocol (RFC 1460) interface. There are no Gnus dependencies in this file.

imap.el
     IMAP library. There are no Gnus dependencies in this file.

ietf-drums.el
     Functions for parsing RFC822bis headers. There are no Gnus dependencies in this file.

rfc1843.el
     HZ (rfc1843) decoding.  HZ is a data format for exchanging files of arbitrarily mixed Chinese and ASCII characters. rfc1843-gnus-setup seem to be useful only for Gnus.  Maybe this function should be relocated to remove dependencies on Gnus.  Other minor dependencies: gnus-newsgroup-name could be eliminated by using an optional argument to rfc1843-decode-article-body.

rfc2045.el
     Functions for decoding rfc2045 headers

rfc2047.el
     Functions for encoding and decoding rfc2047 messages

rfc2104.el
     RFC2104 Hashed Message Authentication Codes

rfc2231.el
     Functions for decoding rfc2231 headers

flow-fill.el
     Interpret RFC2646 "flowed" text There are no Gnus dependencies in this file.

message
-------

All message composition from Gnus (both mail and news) takes place in Message mode buffers.  Message mode is intended to be a replacement for Emacs mail mode.  There should be no Gnus dependencies in message.el.

Gnus backends
-------------

The files nn*.el provide functionality for accessing NNTP (nntp.el), IMAP (nnimap.el) and several other Mail back ends (probably nnml.el, nnfolder.el and nnmaildir.el are the ones most widely used mail back ends).

Compatibility
=============

Gnus Maintainance Guide
***********************

Stable and development versions
===============================

The CVS trunk is developed quite actively.

Syncing
=======

I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to require more manual work.

By default I sync about once a week.  I also try to follow any Gnus threads on the mailing lists and make sure any changes being discussed are kept more up-to-date (so say 1-2 days delay for "topical" changes).

BTW, just to add even more verbose explanation about the syncing thing:

Basically my idea is that the Emacs-Gnus gateway will cause all common files in Emacs and Gnus v5-10 to be identical except when there's a very good reason (e.g., the Gnus version string in Emacs says "5.11", but the v5-10 version string remains "5.10.whatever").  Furthermore, all changes in these files in either Emacs or the v5-10 branch will be installed into the Gnus CVS trunk, again except where there's a good reason (typically so far the only exception has been that the changes already exist in the trunk in modified form).  Because of this, when the next Emacs Gnus upgrade comes, it should be very easy -- just plonk in the files from the Gnus trunk without worrying about lost changes from the Emacs tree.

The effect of this is that as hacker, you should generally only have to make changes in one place:

1) If it's a file which is thought of as being outside of Gnus (e.g., the new "encrypt.el"), you should probably make the change in the Emacs tree, and it will show up in the Gnus tree a few days later.

If you don't have Emacs CVS access (or it's inconvenient), you can change such a file in the v5-10 branch, and it should propagate to Emacs CVS -- however, it will get some extra scrutiny (by me) to see if the changes are possibly controversial and need discussion on the mailing list.  [Many changes are obvious bug-fixes however, so often there won't be any problem.]

2) If it's to a Gnus file, and it's important enough that it should be part of Emacs/v5-10, then you can make the change on the v5-10 branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few days later).

If you know that there will be conflicts (perhaps because the affected source code is different in v5-10 and the Gnus CVS trunk), then you can install your change in both places, and when I try to sync them, there will be a conflict -- however, since in most such cases there would be a conflict _anyway_, it's often easier for me to resolve it simply if I see two "identical" changes, and can just choose the proper one, rather than having to actually fix the code.

3) For general Gnus development changes, of course you just make the change on the Gnus CVS trunk and it goes into Emacs a few years later... :-)

Of course in any case, if you just can't wait for me to sync your change, you can commit it in more than one place and probably there will be no problem; usually the changes are textually identical anyway, so can be easily resolved automatically (sometimes I notice silly things in such multiple commits, like whitespace differences, and unify those ;-).

Miscellanea
===========

GNUS-NEWS
=========

Starting from No Gnus, the GNUS-NEWS is created from texi/gnus-news.texi.  Don't edit GNUS-NEWS.  Edit texi/gnus-news.texi, type make GNUS-NEWS in the texi directory and commit GNUS-NEWS and texi/gnus-news.texi.