X-Git-Url: http://git.chise.org/gitweb/?p=chise%2Fxemacs-chise.git.1;a=blobdiff_plain;f=etc%2FBETA;h=bc85993853d098e4d5ce40ed32e264fedcc152bf;hp=af0b29a985efedfeb1b7156761356a7aa44ef7bf;hb=d81014e89b5102527e5b50aac62edeed2955671d;hpb=716cfba952c1dc0d2cf5c968971f3780ba728a89 diff --git a/etc/BETA b/etc/BETA index af0b29a..bc85993 100644 --- a/etc/BETA +++ b/etc/BETA @@ -3,59 +3,111 @@ * Introduction ============== -You are running an experimental version of XEmacs. Please do not -report problems with Beta XEmacs to comp.emacs.xemacs. Report them to -xemacs-beta@xemacs.org. +You are running a potentially unstable version of XEmacs. Please do +not report problems with Beta XEmacs to comp.emacs.xemacs. Report +them to , preferably with +'M-x report-xemacs-bug RET'. -** XEmacs Beta Mailing List -=========================== +** Mailing Lists +================ -*** Subscribing ---------------- +*** XEmacs Beta Mailing List +---------------------------- -If you are not subscribed to the XEmacs beta list you should be. Send -an email message to xemacs-beta-request@xemacs.org with `subscribe' -(without the quotes) as the BODY of the message. +If you are not subscribed to the XEmacs beta list you should be. +Currently all discussion of development issues, including bug reports +and coding discussion, takes place on the XEmacs Beta mailing list. +Only patches and administrative actions regarding patches are sent +elsewhere (to the XEmacs Patches list). -*** Unsubscribing ------------------ +*** XEmacs Patches Mailing List +------------------------------- -To unsubscribe from the list send an email message to -xemacs-beta-request@xemacs.org with `unsubscribe' (without the quotes) -as the BODY of the message. +XEmacs Patches records proposed changes to XEmacs, and their +disposition. It is open subscription, and all patches that are +seriously proposed for inclusion in XEmacs should be posted here. You +can follow progress of your patch by subscribing to the mailing list +or in the archives. -*** Administrivia ------------------ +Besides patches, only actions by members of the XEmacs Review Board +should be posted to this list. All discussion should be redirected to +XEmacs Beta or XEmacs Design. -The XEmacs beta list is managed by the Majordomo mailing list package, -and the usual Majordomo commands work. Do not send mailing list -requests to the main address (xemacs-beta@xemacs.org), always send -them to xemacs-beta-request@xemacs.org. If you have problems with the -list itself, they should be brought to the attention of the XEmacs -Mailing List manager Jason Mastaler . +*** XEmacs Design Mailing List +------------------------------ +XEmacs Design is for design discussions such as adding major features +or whole modules, or reimplementation of existing functions, to XEmacs. + +*** List Administrivia +---------------------- + +In the descriptions below, the word LIST (all uppercase) is a +variable. Substitute "beta", "design", or "patches" as appropriate +(to get "xemacs-beta" as the mailbox for the XEmacs Beta mailing list, +or for its URL). + +The XEmacs mailing lists are managed by the Mailman mailing list +package, and the usual Mailman commands work. Do not send mailing +list requests to the main address (), always +send them to . If you have problems +with the list itself, they should be brought to the attention of the +XEmacs Mailing List manager (the same +mailbox, "list-manager", for all lists). All public mailing lists +have searchable archives. The URL is + + http://list-archive.xemacs.org/xemacs-LIST + +Note that the xemacs-LIST-admin address is used internally by the +Mailman software; it is NOT a synonym for xemacs-LIST-request. + +*** Managing your subscription via the Web +------------------------------------------ + +Subscription, unsubscription, and options (such as digests and +temporarily suspending delivery) can be accomplished via the web +interface at . + +*** Subscribing by e-mail +------------------------- + +Send an email message to with +`subscribe' (without the quotes) as the BODY of the message. + +*** Unsubscribing by e-mail +--------------------------- + +Send an email message to with +`unsubscribe' (without the quotes) as the BODY of the message. ** Beta Release Schedule ======================== -The URL ftp://ftp.xemacs.org/pub/xemacs/beta/README always contains -the best estimate of when the next beta XEmacs will be released. For -weekend betas the release time is generally in the vicinity of 2PM to -5PM US Pacific Time (Universal Time minus 8 hours). For weekday -betas, the release time is generally in the vicinity of 8PM to -Midnight US Pacific Time on the listed day. +We would like to achieve a weekly or fortnightly release cycle (you +know the Open Source model: release early, release often), and in a +perfect world that would indeed be the case. There are at least three +things that often get in the way of that goal: 1) The Release Manager +has a life outside of XEmacs (hard to believe, I know, but true), +2) we like to make releases that will build (at least on the Release +Manager's box), and 3) Murphy likes to throw a spanner in the works +right when you least expect it (Murphy's Law: Whatever can go wrong, +will go wrong). -Betas are nominally a week apart, scheduled on every Saturday. -Midweek releases are made when a serious enough problem warrants it. +If you'd like to keep right up to date and ride the bleeding edge, use +CVS (see ). If you +can't use CVS for some reason and must use FTP, please let us know. +it will make it more likely that we release betas more often. ** Reporting Problems ===================== The best way to get problems fixed in XEmacs is to submit good problem -reports. Since this is beta software, problems are certain to exist. -Please read through all of part II of the XEmacs FAQ for an overview -of problem reporting. Other items which are most important are: +reports, 'M-x report-xemacs-bug RET' will help you do this (assuming +you have a usable XEmacs). Since this is beta software, problems are +certain to exist. Please read through all of part II of the XEmacs +FAQ for an overview of problem reporting. Other items which are most +important are: 1. Do not submit C stack backtraces without line numbers. Since it is possible to compile optimized with debug information with GCC @@ -66,11 +118,16 @@ of problem reporting. Other items which are most important are: problem is actually occurring. 2. Attempt to recreate the problem starting with an invocation of - XEmacs with `xemacs -q -no-site-file'. Quite often, problems are - due to package interdependencies, and the like. An actual bug in - XEmacs should be reproducible in a default configuration without - loading any special packages (or the one or two specific packages - that cause the bug to appear). + XEmacs with `xemacs -no-autoloads'. Quite often, problems are + due to package interdependencies, and the like. An actual bug + in XEmacs should be reproducible in a default configuration + without loading any special packages (or the one or two specific + packages that cause the bug to appear). If you have trouble + getting anything to work at all with the above invocation, use + `xemacs -vanilla' instead. If you need to load your user init + file or the site file to get the problem to occur, then it has + something to do with them, and you should try to isolate the + issue in those files. 3. A picture can be worth a thousand words. When reporting an unusual display, it is generally best to capture the problem in a @@ -84,7 +141,9 @@ of problem reporting. Other items which are most important are: ===================== In addition to the normal tar distribution, XEmacs source is now -available via CVS. Please see the URL: . +available via CVS. Please see + + http://www.xemacs.org/Develop/cvsaccess.html * Compiling Beta XEmacs ======================= @@ -92,15 +151,15 @@ available via CVS. Please see the URL: . ** Building an XEmacs from patches ================================== -All beta releases of XEmacs are included with patches from the -previous version in an attempt to keep bandwidth requirements down. -Patches should be applied with the GNU patch program in something like -the following. Let's say you're upgrading XEmacs 20.15-beta10 to -XEmacs 20.15-beta11 and you have a full unmodified XEmacs 20.15-beta10 -source tree to work with. Cd to the top level directory and issue the +All beta releases of XEmacs are included with patches from the previous +version in an attempt to keep bandwidth requirements down. Patches +should be applied with the GNU patch program in something like the +following. Let's say you're upgrading XEmacs 21.5-beta9 to XEmacs +21.5-beta10 and you have a full unmodified XEmacs 21.5-beta9 source +tree to work with. Change to the top level directory and issue the shell command: -$ gunzip -c /tmp/xemacs-20.15-b10-20.15-b11.patch.gz | patch -p1 +$ gunzip -c /tmp/xemacs-21.5.9-21.5.10.patch.gz | patch -p1 After patching, check to see that no patches were missed by doing $ find . -name \*.rej -print @@ -111,80 +170,110 @@ before building XEmacs. After seeing that there were no rejections, issue the commands $ ./config.status --recheck -$ make beta +$ make beta > ./beta.err 2>&1 +$ make check > ./xemacs-make-check.err 2>&1 -and go play minesweep for a while on an older XEmacs while the binary -is rebuilt. +Redirect the output from make to those files because you'll use them +later when you send off a build report with 'M-x build-report RET' ** Building XEmacs from a full distribution -============================================== +=========================================== Locate a convenient place where you have at least 100MB of free space and issue the command -$ gunzip -c /tmp/xemacs-20.15-b11.tar.gz | tar xvf - +$ gunzip -c /tmp/xemacs-21.5.10.tar.gz | tar xvf - -(or simply `tar zxvf /tmp/xemacs-20.15-b11.tar.gz' if you use GNU tar). +(or simply `tar zxvf /tmp/xemacs-21.5.10.tar.gz' if you use GNU tar). cd to the top level directory and issue an appropriate configure command. One maintainer uses the following at the time of this writing: ./configure \ - --cflags="-mpentium -march=pentium -O6 -g -fno-peep-spills" \ - --error-checking=all --debug=yes \ - --with-scrollbars=athena3d --with-dialogs=athena3d \ - --with-mule --with-xfs --with-xim=xlib - -Part of the configure output is a summary that looks something like: - -uname -a: Linux altair.xemacs.org 2.0.32 #2 Sun Nov 16 18:52:14 PST 1997 i586 - -./configure '--cflags=-mpentium -march=pentium -O6 -g -fno-peep-spills' '--error-checking=all' '--debug=yes' '--with-scrollbars=athena3d' '--with-dialogs=athena3d' '--with-mule' '--with-xfs' '--with-xim=xlib' - - -XEmacs 21.0-b34 "Oberhasli-pre2" configured for `i586-pc-linux'. + --extra-verbose \ + --site-prefixes=/usr/local/pgsql:/usr/local/BerkeleyDB.4.1 \ + --dynamic=yes --with-gtk=no --with-gnome=no --with-toolbars \ + --with-wmcommand --with-athena=next --with-menubars=lucid \ + --with-scrollbars=athena --with-dialogs=athena --with-widgets=athena \ + --with-gif --with-sound=native,noesd --with-site-lisp=no \ + --with-site-modules --pdump --with-mule --with-xfs --debug \ + --error-checking=all --memory-usage-stats --use-kkcc \ + --with-clash-detection + +Part of the configure output is a summary that looks something +like the following. (this summary is also available as the file +'Installation' in the top directory of your build tree, and via +the command 'M-x describe-installation RET'). + +uname -a: Linux eicq 2.4.20 #1 Wed Dec 18 02:14:29 EST 2002 i586 unknown + +./configure '--extra-verbose' '--site-prefixes=/usr/local/pgsql:/usr/local/BerkeleyDB.4.1' '--dynamic=yes' '--with-gtk=no' '--with-gnome=no' '--with-toolbars' '--with-wmcommand' '--with-athena=next' '--with-menubars=lucid' '--with-scrollbars=athena' '--with-dialogs=athena' '--with-widgets=athena' '--with-gif' '--with-sound=native,noesd' '--with-site-lisp=no' '--with-site-modules' '--pdump' '--with-mule' '--with-xfs' '--debug' '--error-checking=all' '--memory-usage-stats' '--use-kkcc' '--with-clash-detection' + + +XEmacs 21.5-b10 "burdock" (+CVS-20030131) configured for `i586-pc-linux'. + + +Compilation / Installation: + Source code location: /usr/local/src/xemacs + Installation prefix: /usr/local + Additional prefixes: /usr/local/pgsql /usr/local/BerkeleyDB.4.1 + Operating system description file: `s/linux.h' + Machine description file: `m/intel386.h' + Compiler: gcc -Wall -Wno-switch -Winline -Wmissing-prototypes -Wsign-compare -Wundef -Wstrict-prototypes -Wshadow -Wmissing-declarations -O1 -ggdb3 -Wall -Wchar-subscripts -Wunused -Wundef -Wshadow -Wsign-compare -Wmissing-declarations -march=k6 + Relocating allocator for buffers: no + GNU version of malloc: yes + - Using Doug Lea's new malloc from the GNU C Library. + +Window System: + Compiling in support for the X window system: + - X Windows headers location: /usr/X11/include + - X Windows libraries location: /usr/X11/lib + - Handling WM_COMMAND properly. + Compiling in support for the Athena widget set: + - Athena headers location: X11/neXtaw + - Athena library to link: neXtaw + Using Lucid menubars. + Using Athena scrollbars. + Using Athena dialog boxes. + Using Athena native widgets. - Where should the build process find the source code? /home/xemacs/xemacs-20.0 - What installation prefix should install use? /usr/local - What operating system and machine description files should XEmacs use? - `s/linux.h' and `m/intel386.h' - What compiler should XEmacs be built with? gcc -mpentium -march=pentium -O6 -g -fno-peep-spills - Should XEmacs use the GNU version of malloc? yes - (Using Doug Lea's new malloc from the GNU C Library.) - Should XEmacs use the relocating allocator for buffers? yes - What window system should XEmacs use? x11 - Where do we find X Windows header files? /usr/X11/include - Where do we find X Windows libraries? /usr/X11/lib - Compiling in support for XAUTH. - Compiling in support for XPM images. - Compiling in support for X-Face message headers. - Compiling in support for GIF image conversion. - Compiling in support for JPEG image conversion. - Compiling in support for PNG image conversion. - Compiling in support for TIFF image conversion. - Compiling in native sound support. - Compiling in support for Berkeley DB. - Compiling in support for GNU DBM. +TTY: Compiling in support for ncurses. Compiling in support for GPM (General Purpose Mouse). - Compiling in Mule (multi-lingual) support. - Compiling in XIM (X11R5+ I18N input method) support. - Using raw Xlib to provide XIM support. - Using XFontSet to provide bilingual menubar. - Compiling in support for Canna on Mule. - Compiling in support for the WNN input method on Mule. - Using WNN version 6. - Compiling in support for OffiX. - Compiling in support for proper session-management. - Using Lucid menubars. - Using Athena-3d scrollbars. - Using Athena-3d dialog boxes. - Compiling in DLL support. - movemail will use "dot-locking" for locking mail spool files. - Using Lisp_Objects with minimal tagbits. - Compiling in extra code for debugging. - Compiling in code for checking XEmacs memory usage. + +Images: + Compiling in support for GIF images (builtin). + Compiling in support for XPM images. + Compiling in support for PNG images. + Compiling in support for JPEG images. + Compiling in support for TIFF images. + Compiling in support for X-Face message headers. + +Sound: + Compiling in support for sound (native). + +Databases: + Compiling in support for Berkeley database. + Compiling in support for PostgreSQL. + - Using PostgreSQL header file: libpq-fe.h + - Using PostgreSQL V7 bindings. + +Internationalization: + Compiling in support for Mule (multi-lingual Emacs). + Compiling in support for XIM (X11R5+ I18N input method). + - Using raw Xlib to provide XIM support. + - Using XFontSet to provide bilingual menubar. + +Mail: + Compiling in support for "dot-locking" mail spool file locking method. + +Other Features: + Inhibiting IPv6 canonicalization at startup. + Compiling in support for dynamic shared object modules. + Using the new GC algorithms. + Using the new portable dumper. + Compiling in support for extra debugging code. WARNING: --------------------------------------------------------- WARNING: Compiling in support for runtime error checking. WARNING: XEmacs will run noticeably more slowly as a result. @@ -193,11 +282,27 @@ XEmacs 21.0-b34 "Oberhasli-pre2" configured for `i586-pc-linux'. -Then type `make' and you should have a working XEmacs. +Then... + +$ make > ./beta.err 2>&1 +$ make check > ./xemacs-make-check.err 2>&1 + +...and you should have a working XEmacs. After you have verified that you have a functional editor, fire up your favorite mail program and send a build report to -xemacs-build-reports@xemacs.org. The build report should include +. + +Preferably this is best done from XEmacs, following these simple steps: + +M-x customize-group RET build-report RET +M-x build-report RET + +See also + + +If you create the report manually by other means, here is what the +build report should include: 1. Your hardware configuration (OS version, etc.) @@ -217,85 +322,24 @@ xemacs-build-reports@xemacs.org. The build report should include 5. Any other unusual items you feel should be brought to the attention of the developers. -** Creating patches for submission -================================== - -Patches to XEmacs should be mailed to . -Each patch will be reviewed by the patches review board, and will be -acked and added to the distribution, or rejected with an explanation. - -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 . - -Emailed patches should preferably be sent in MIME format and quoted -printable encoding (if necessary). - -When making patches, 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 - -Each patch should be accompanied by an update to the appropriate -ChangeLog file. Please don't mail patches to ChangeLog because they -have an extremely high rate of failure; just mail us the new part of -the ChangeLog you added. - -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. - -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. - -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. - -** Packages directory on the FTP Site -===================================== - -The packages directory - ftp://ftp.xemacs.org/pub/xemacs/beta/xemacs-21.0/packages/ -is divided into subdirectory by the major type of package. +* Packages +========== -drwxr-xr-x 2 beta-f beta-f 1024 Oct 10 00:43 binary-packages -drwxr-xr-x 2 beta-f beta-f 512 Oct 10 00:44 package-sources -drwxr-xr-x 2 beta-f beta-f 512 Oct 10 00:44 utils +[Note: these instructions have been partly updated, but not carefully +reviewed in some time. Caveat tester.] -** Support Utilities (utils) -============================ +Starting with XEmacs 21.1, much of the functionality of XEmacs has +been unbundled into "the packages." For more information about the +package system, see the Info nodes on Packages (in the XEmacs User +Manual) and on Packaging (in the Lisp Reference). -The utils directory contains tools to deal with current Lisp sources that -have not had yet gotten XEmacs package integration. The script `xpackage.sh' -is used with Quassia Gnus. Edit the appropriate variables at the top of -the script to reflect the local configuration and run it in the top level -directory of a Quassia Gnus source tree to install an update to Quassia Gnus. +When bootstrapping XEmacs, you may need to manually install some +packages (at least xemacs-base and efs). These packages are available +by FTP at . -** Binary package installation (binary-packages) -================================================ +** Binary package installation +============================== Prerequisite: XEmacs 21.0-b1. @@ -315,56 +359,271 @@ groups) must be kept in synch. Assuming one is manipulating a directory called `lisp-utils', the command to rebuild the auto-autoloads.el file is: -xemacs-21.0 -vanilla -batch -l autoload -f batch-update-directory lisp-utils +xemacs -vanilla -batch \ + -eval \("setq autoload-package-name \"lisp-utils\""\) \ + -f batch-update-directory lisp-utils The command to rebuild the custom-load.el file is: -xemacs-21.0 -vanilla -batch -l cus-dep \ - -f Custom-make-dependencies lisp-utils +xemacs -vanilla -batch -f Custom-make-dependencies lisp-utils -To bytecompile both of these files the command is: +To byte-compile both of these files the command is: -xemacs-21.0 -vanilla -batch -f batch-byte-compile \ +xemacs -vanilla -batch -f batch-byte-compile \ lisp-utils/auto-autoloads.el lisp-utils/custom-load.el +Of course, being a beta tester, you'd be aware that it is much easier +to manage your XEmacs packages with PUI. + ** Building XEmacs and XEmacs packages from scratch =================================================== -To build everything completely from scratch (not a high priority as a -design goal), the following procedure should work. (I don't recommend -building this way). +To build everything completely from scratch isn't hard, just time +consuming. + +*** Step 1 - grab the sources (core and packages) + +$ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs login + [password: "cvs" (sans quotes)] + +$ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs co -d xemacs-21.5 xemacs -*** Phase 1 -- Get a minimal XEmacs binary with mule to build the package - lisp with. +$ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs co packages -**** Grab a mule-base tarball and install it into a newly created package - directory. +*** Step 2 - build XEmacs -**** Configure XEmacs with mule and a package-path including the - directory created above. +$ cd xemacs-21.5 +$ ./configure [options...] +$ make > ./beta.err 2>&1 +$ make check > ./xemacs-make-check.err 2>&1 -**** Do a `make dist' to build an XEmacs binary. +And optionally: -*** Phase 2 -- Build and install the package lisp. +$ make install > ./xemacs-make-install.err 2>&1 -**** Modify XEmacs.rules for local paths and the XEmacs binary created in - Phase 1. +*** Step 3 - build and install the packages -**** Do a make from the top level package lisp source directory.[1] +$ cd packages +$ cp Local.rules.template Local.rules -**** Do `make bindist's on all the packages you wish to install and - remove the byproduct .tar.gz's. +Then edit Local.rules to suit your needs/environment +see: (Info-goto-node "(xemacs)Local.rules file") for details about +this file. -*** Phase 3 -- If necessary, redump XEmacs - with the packages that require dump-time support and install it. +And then: -**** Reconfigure without Mule if you don't wish a Mule-ish XEmacs, and - rebuild XEmacs. +$ make install -- or - +* Improving XEmacs +================= -**** rm lib-src/DOC src/xemacs; make +** Creating patches for submission +================================== -**** Install or run in-place. +All patches to XEmacs that are seriously proposed for inclusion (eg, +bug fixes) should be mailed to . 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. (If a patch is simply +intended to facilitate discussion, "I mean something that works like +this but this is really rough", a Cc to XEmacs Patches is optional, +but doesn't hurt.) + +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 . + +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 + [Change Logs section] +for details. -Note that this is in essence what `make all-elc' has always done. +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. Context-less unified diffs (-U 0) are also +acceptable. + +*** 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 judgment; +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 or to xemacs-design. If you're not sure +which is more appropriate, send it to xemacs-beta. That is the most +widely read channel. + +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 SUPERSEDES 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ä is currently +serving with Norbert Koch assisting; Steve +Youngs and Stephen Turnbull +also can help) are the most likely sources 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.