-
-
-* Improving XEmacs
-=================
-
-** Creating patches for submission
-==================================
-
-Patches to XEmacs should be mailed to <xemacs-patches@xemacs.org>.
-Each patch will be reviewed by the patches review board, and will be
-acknowledged and added to the distribution, or rejected with an
-explanation. Progress of the patch is tracked on the XEmacs Patches
-mailing list, which is open subscription.
-
-Patches to XEmacs Lisp packages should be sent to the maintainer of
-the package. If the maintainer is listed as `XEmacs Development Team'
-patches should be sent to <xemacs-patches@xemacs.org>.
-
-Emailed patches should preferably be sent in MIME format and quoted
-printable encoding (if necessary).
-
-The simplest way to create well-formed patches is to use CVS and
-Didier Verna's Patcher library (available as patcher.el in the
-xemacs-devel package). Patcher is new and requires some setup, but
-most of the core developers are now using it for their own patches.
-Patcher also can be configured to create patches for several projects,
-and recognize the project from the directory it is invoked in. This
-makes it a useful general tool (as long as XEmacs-style patches are
-accepted at your other projects, which is likely since they conform to
-the GNU standards).
-
-When making patches by hand, please use the `-u' option, or if your
-diff doesn't support it, `-c'. Using ordinary (context-free) diffs
-are notoriously prone to error, since line numbers tend to change when
-others make changes to the same source file.
-
-An example of the `diff' usage:
-
-$ diff -u OLDFILE NEWFILE
-
--or-
-
-$ diff -c OLDFILE NEWFILE
-
-Also, it is helpful if you create the patch in the top level of the
-XEmacs source directory:
-
-$ cp -p lwlib/xlwmenu.c lwlib/xlwmenu.c.orig
- hack, hack, hack....
-$ diff -u lwlib/xlwmenu.c.orig lwlib/xlwmenu.c
-
-Also note that if you cut & paste from an xterm to an XEmacs mail buffer
-you will probably lose due to tab expansion. The best thing to do is
-to use an XEmacs shell buffer to run the diff commands, or ...
-M-x cd to the appropriate directory, and issue the command `C-u M-!' from
-within XEmacs.
-
-Patches should be as single-minded as possible. Mammoth patches can
-be very difficult to place into the right slot. They are much easier
-to deal with when broken down into functional or conceptual chunks.
-The patches submitted by Kyle Jones and Hrvoje Niksic are stellar
-examples of how to Do The Right Thing.
-
-Each patch should be accompanied by an update to the appropriate
-ChangeLog file. Guidelines for writing ChangeLog entries is governed
-by the GNU coding standards. Please see
- http://www.gnu.org/prep/standards_toc.html [Change Logs section]
-for details.
-
-Do not submit context diffs (either -c or -u) of ChangeLogs. Because
-of the "stack" nature of ChangeLogs (new entries are always pushed on
-the top), context diffs will fail to apply more often than they
-succeed. Simply cutting and pasting the entry from an Emacs buffer to
-the mail buffer (beware of tab expansion!) is probably easiest. The
-Patcher library also will set up your ChangeLogs for you, and copy
-them to the mail. Contextless unified diffs (-U 0) are also
-acceptable but perhaps more trouble than they are worth.
-
-*** Patch discussion etiquette
--------------------------------
-
-If you intend a patch for _application_ to the sources as is, _always_
-post it to xemacs-patches, even if there are minor points you would
-like to have discussed by others. Not doing so will resulting in
-patches getting "lost". If you expect that the patch will not be
-acceptable, but are using it to stimulate discussion, then don't post
-to xemacs-patches. Intermediate cases are up to your judgement;
-unless you're sure you'll follow up with a "real" patch, better to err
-on the side of posting to xemacs-patches.
-
-Discussion of the _content_ of the patch (ie responses to reviewer
-comments beyond "that's right, ok, I'll do it your way") should _always_
-be posted to xemacs-beta. (We may split xemacs-beta into code
-discussion and stuff that is more relevant to non-developer testers at
-some point, but at this point xemacs-beta is the correct place for
-this.)
-
-If discussion results in a bright idea and you come up with a new
-patch, normally you should post it to both mailing lists. The people
-discussing on XEmacs Beta will want to know the outcome of the thread,
-and you need to submit to XEmacs Patches as the "list of record."
-
-If the old patch has been applied to CVS, then just submit the new one
-as usual. If it has not been applied, then it is best to submit a new
-patch against CVS. If possible do this as a reply to the original
-patch post, or something following it in the thread. (The point is to
-get the original patch post's Message-ID in your References header.)
-In this case, also use the keyword SUPERCEDES in the Subject header to
-indicate that the old patch is no longer valid, and that this one
-replaces it.
-
-These rules will result in a fair number of cross posts, but we don't
-yet have a better way to handle that.
-
-Note: Developers should never post to xemacs-patches unless there is a
-patch in the post. We plan to enforce this with an automatic filter.
-
-The exceptions are administrative. If you have commit authorization,
-then post a short COMMIT notice to xemacs-patches when you commit to
-CVS. Members of the Review Board will also post short notices of
-administrative action (APPROVE, VETO, QUERY, etc) to xemacs-patches.
-
-** Large contributions
-======================
-
-Perhaps you have a whole new mode, or a major synchronization with
-upstream for a neglected package, or a synchronization with GNU Emacs
-you would like to contribute. We welcome such contributions, but they
-are likely to be relatively controversial, generate more comments and
-requests for revision, and take longer to integrate. Please be
-patient with the process.
-
-*** Updates to existing packages
---------------------------------
-
-If a package has gotten a bit out of date, or even started to bitrot,
-we welcome patches to synchronize it with upstream/GNU Emacs versions.
-Most packages end up varying somewhat from their GNU origins. See
-"Syncing with GNU Emacs" for hints. Note that if you do a reasonably
-large amount of syncing with GNU Emacs, you should log this in the
-file itself as well as in the ChangeLog.
-
-If the package is important to you, please consider becoming the
-maintainer. (See "New packages", below.)
-
-*** New packages
-----------------
-
-If you have a new mode or other large addition that does not require
-changes to the core, please consider submitting it as a package, and
-becoming the maintainer. You get direct commit privileges to the
-repository for your package, "approval" privileges for your own
-patches as well as third party patches to your package, and some
-degree of veto power over patches you don't like. In return, you are
-expected to maintain friendly liaison with the upstream developer (if
-you aren't the upstream developer), keep watch on the XEmacs Patches
-list for relevant patches, and be available by email to other
-developers for discussion of changes that impact your package. It's
-also a pretty standard route to the "core" development group, where we
-have plenty of extra work waiting for volunteers.
-
-You don't have to become the maintainer, but it virtually ensures
-rapid acceptance of the package.
-
-For help in creating new packages, see the (rather sparse) discussions
-in the XEmacs User's Guide and the Lisp Reference Manual. The XEmacs
-Package Release Engineer (Ville Skyttä <ville.skytta@xemacs.org> is
-currently serving with Peter Brown <rendhalver@users.sourceforge.net>
-assisting; Steve Youngs <youngs@xemacs.org> and Stephen Turnbull
-<stephen@xemacs.org> also can help) is the most likely source of advice.
-
-*** Syncing with GNU Emacs
---------------------------
-
-Syncing with GNU Emacs is an important activity. Although each
-version has its advantages and areas of concentration, it is very
-desirable that common functionality share specifications and APIs.
-When porting GNU code to XEmacs, the following points should be given
-special attention:
-
- o Recent GNU Emacsen cannot be built without Mule, but XEmacs can.
- Make sure your changes do not assume the presence of Mule.
-
- o GNU Emacs nomenclature often differs from that of XEmacs.
- Sometimes syncing the names is desirable, other times not.
-
- o GNU Emacs functionality often differs from that of XEmacs.
- Syncing functionality is often controversial.
-
-It is important that you let other developers know that
-synchronization has taken place, to what degree, and when. For this
-purpose, we use comments of the form
-
-/* Synched up with: FSF 21.3 by Stephen Turnbull */
-
-in the source file itself, as the last element of the prefatory
-material (copyright notice and commentary). Obviously the comment
-marker needs to be changed to leading semicolons for Lisp, but
-otherwise the format is the same.
-
-Of course you should note syncing as the purpose in the ChangeLog,
-too. But entries get buried deep in the ChangeLog file, and may even
-get moved to a separate ChangeLog.OLD file for rarely synched files.
-
-Rather than dates we use the version of GNU Emacs to sync to. If the
-synchronization is partial, add a new comment describing what has
-actually been synched, leaving the description of the last full sync
-in place. At each full sync, remove all previous synchronization
-comments.
-
-This applies to Lisp that we have broken out into packages, but
-remains in the GNU Emacs core, as well to core Lisp in XEmacs.