428
+ − 1 -*- mode:outline -*-
+ − 2
+ − 3 * Introduction
+ − 4 ==============
+ − 5
743
+ − 6 You are running a potentially unstable version of XEmacs. Please do
+ − 7 not report problems with Beta XEmacs to comp.emacs.xemacs. Report
1250
+ − 8 them to <xemacs-beta@xemacs.org>, preferably with
+ − 9 'M-x report-xemacs-bug RET'.
428
+ − 10
743
+ − 11 ** Mailing Lists
+ − 12 ================
+ − 13
+ − 14 *** XEmacs Beta Mailing List
+ − 15 ----------------------------
428
+ − 16
743
+ − 17 If you are not subscribed to the XEmacs beta list you should be.
+ − 18 Currently all discussion of development issues, including bug reports
+ − 19 and coding discussion, takes place on the XEmacs Beta mailing list.
+ − 20 Only patches and administrative actions regarding patches are sent
+ − 21 elsewhere (to the XEmacs Patches list).
+ − 22
1044
+ − 23 *** XEmacs Patches Mailing List
+ − 24 -------------------------------
428
+ − 25
743
+ − 26 XEmacs Patches records proposed changes to XEmacs, and their
1044
+ − 27 disposition. It is open subscription, and all patches that are
+ − 28 seriously proposed for inclusion in XEmacs should be posted here. You
743
+ − 29 can follow progress of your patch by subscribing to the mailing list
+ − 30 or in the archives.
+ − 31
1044
+ − 32 Besides patches, only actions by members of the XEmacs Review Board
+ − 33 should be posted to this list. All discussion should be redirected to
+ − 34 XEmacs Beta or XEmacs Design.
+ − 35
+ − 36 *** XEmacs Design Mailing List
+ − 37 ------------------------------
+ − 38
+ − 39 XEmacs Design is for design discussions such as adding major features
+ − 40 or whole modules, or reimplementation of existing functions, to XEmacs.
+ − 41
+ − 42 *** List Administrivia
+ − 43 ----------------------
428
+ − 44
743
+ − 45 In the descriptions below, the word LIST (all uppercase) is a
1044
+ − 46 variable. Substitute "beta", "design", or "patches" as appropriate
+ − 47 (to get "xemacs-beta" as the mailbox for the XEmacs Beta mailing list,
1301
+ − 48 or <http://www.xemacs.org/Lists/#xemacs-beta> for its URL).
428
+ − 49
743
+ − 50 The XEmacs mailing lists are managed by the Mailman mailing list
+ − 51 package, and the usual Mailman commands work. Do not send mailing
1301
+ − 52 list requests to the main address (<xemacs-LIST@xemacs.org>), always
+ − 53 send them to <xemacs-LIST-request@xemacs.org>. If you have problems
743
+ − 54 with the list itself, they should be brought to the attention of the
+ − 55 XEmacs Mailing List manager <list-manager@xemacs.org> (the same
+ − 56 mailbox, "list-manager", for all lists). All public mailing lists
+ − 57 have searchable archives. The URL is
+ − 58
+ − 59 http://list-archive.xemacs.org/xemacs-LIST
428
+ − 60
1044
+ − 61 Note that the xemacs-LIST-admin address is used internally by the
+ − 62 Mailman software; it is NOT a synonym for xemacs-LIST-request.
+ − 63
743
+ − 64 *** Managing your subscription via the Web
+ − 65 ------------------------------------------
+ − 66
+ − 67 Subscription, unsubscription, and options (such as digests and
+ − 68 temporarily suspending delivery) can be accomplished via the web
1301
+ − 69 interface at <http://www.xemacs.org/Lists/#xemacs-LIST>.
428
+ − 70
743
+ − 71 *** Subscribing by e-mail
+ − 72 -------------------------
+ − 73
1301
+ − 74 Send an email message to <xemacs-LIST-request@xemacs.org> with
743
+ − 75 `subscribe' (without the quotes) as the BODY of the message.
428
+ − 76
743
+ − 77 *** Unsubscribing by e-mail
+ − 78 ---------------------------
+ − 79
1301
+ − 80 Send an email message to <xemacs-LIST-request@xemacs.org> with
743
+ − 81 `unsubscribe' (without the quotes) as the BODY of the message.
428
+ − 82
+ − 83 ** Beta Release Schedule
+ − 84 ========================
+ − 85
1250
+ − 86 We would like to achieve a weekly or fortnightly release cycle (you
+ − 87 know the Open Source model: release early, release often), and in a
+ − 88 perfect world that would indeed be the case. There are at least three
+ − 89 things that often get in the way of that goal: 1) The Release Manager
+ − 90 has a life outside of XEmacs (hard to believe, I know, but true),
+ − 91 2) we like to make releases that will build (at least on the Release
+ − 92 Manager's box), and 3) Murphy likes to throw a spanner in the works
+ − 93 right when you least expect it (Murphy's Law: Whatever can go wrong,
+ − 94 will go wrong).
+ − 95
+ − 96 If you'd like to keep right up to date and ride the bleeding edge, use
+ − 97 CVS (see <http://www.xemacs.org/Develop/cvsaccess.html>). If you
+ − 98 can't use CVS for some reason and must use FTP, please let us know.
+ − 99 it will make it more likely that we release betas more often.
+ − 100
428
+ − 101
+ − 102 ** Reporting Problems
+ − 103 =====================
+ − 104
+ − 105 The best way to get problems fixed in XEmacs is to submit good problem
1250
+ − 106 reports, 'M-x report-xemacs-bug RET' will help you do this (assuming
+ − 107 you have a usable XEmacs). Since this is beta software, problems are
+ − 108 certain to exist. Please read through all of part II of the XEmacs
+ − 109 FAQ for an overview of problem reporting. Other items which are most
+ − 110 important are:
428
+ − 111
+ − 112 1. Do not submit C stack backtraces without line numbers. Since it
+ − 113 is possible to compile optimized with debug information with GCC
+ − 114 it is never a good idea to compile XEmacs without the -g flag.
+ − 115 XEmacs runs on a variety of platforms, and often it is not
+ − 116 possible to recreate problems which afflict a specific platform.
+ − 117 The line numbers in the C stack backtrace help isolate where the
+ − 118 problem is actually occurring.
+ − 119
+ − 120 2. Attempt to recreate the problem starting with an invocation of
1255
+ − 121 XEmacs with `xemacs -no-autoloads'. Quite often, problems are
+ − 122 due to package interdependencies, and the like. An actual bug
+ − 123 in XEmacs should be reproducible in a default configuration
+ − 124 without loading any special packages (or the one or two specific
+ − 125 packages that cause the bug to appear). If you have trouble
+ − 126 getting anything to work at all with the above invocation, use
+ − 127 `xemacs -vanilla' instead. If you need to load your user init
+ − 128 file or the site file to get the problem to occur, then it has
+ − 129 something to do with them, and you should try to isolate the
+ − 130 issue in those files.
428
+ − 131
+ − 132 3. A picture can be worth a thousand words. When reporting an
+ − 133 unusual display, it is generally best to capture the problem in a
+ − 134 screen dump and include that with the problem report. The easiest
+ − 135 way to get a screen dump is to use the xv program and its grab
+ − 136 function. Save the image as a GIF to keep bandwidth requirements
+ − 137 down without loss of information. MIME is the preferred method
+ − 138 for making the image attachments.
+ − 139
+ − 140 ** Getting the Source
+ − 141 =====================
+ − 142
+ − 143 In addition to the normal tar distribution, XEmacs source is now
743
+ − 144 available via CVS. Please see
+ − 145
+ − 146 http://www.xemacs.org/Develop/cvsaccess.html
428
+ − 147
+ − 148 * Compiling Beta XEmacs
+ − 149 =======================
+ − 150
+ − 151 ** Building an XEmacs from patches
+ − 152 ==================================
+ − 153
1250
+ − 154 All beta releases of XEmacs are included with patches from the previous
+ − 155 version in an attempt to keep bandwidth requirements down. Patches
+ − 156 should be applied with the GNU patch program in something like the
+ − 157 following. Let's say you're upgrading XEmacs 21.5-beta9 to XEmacs
+ − 158 21.5-beta10 and you have a full unmodified XEmacs 21.5-beta9 source
+ − 159 tree to work with. Change to the top level directory and issue the
428
+ − 160 shell command:
+ − 161
1250
+ − 162 $ gunzip -c /tmp/xemacs-21.5.9-21.5.10.patch.gz | patch -p1
428
+ − 163
+ − 164 After patching, check to see that no patches were missed by doing
+ − 165 $ find . -name \*.rej -print
+ − 166
+ − 167 Any rejections should be treated as serious problems to be resolved
+ − 168 before building XEmacs.
+ − 169
+ − 170 After seeing that there were no rejections, issue the commands
+ − 171
+ − 172 $ ./config.status --recheck
1250
+ − 173 $ make beta > ./beta.err 2>&1
+ − 174 $ make check > ./xemacs-make-check.err 2>&1
428
+ − 175
1250
+ − 176 Redirect the output from make to those files because you'll use them
+ − 177 later when you send off a build report with 'M-x build-report RET'
428
+ − 178
+ − 179 ** Building XEmacs from a full distribution
1024
+ − 180 ===========================================
428
+ − 181
+ − 182 Locate a convenient place where you have at least 100MB of free space
+ − 183 and issue the command
+ − 184
1250
+ − 185 $ gunzip -c /tmp/xemacs-21.5.10.tar.gz | tar xvf -
428
+ − 186
1250
+ − 187 (or simply `tar zxvf /tmp/xemacs-21.5.10.tar.gz' if you use GNU tar).
428
+ − 188
+ − 189 cd to the top level directory and issue an appropriate configure
+ − 190 command. One maintainer uses the following at the time of this
+ − 191 writing:
+ − 192
+ − 193 ./configure \
1250
+ − 194 --extra-verbose \
+ − 195 --site-prefixes=/usr/local/pgsql:/usr/local/BerkeleyDB.4.1 \
+ − 196 --dynamic=yes --with-gtk=no --with-gnome=no --with-toolbars \
+ − 197 --with-wmcommand --with-athena=next --with-menubars=lucid \
+ − 198 --with-scrollbars=athena --with-dialogs=athena --with-widgets=athena \
+ − 199 --with-gif --with-sound=native,noesd --with-site-lisp=no \
+ − 200 --with-site-modules --pdump --with-mule --with-xfs --debug \
+ − 201 --error-checking=all --memory-usage-stats --use-kkcc \
+ − 202 --with-clash-detection
428
+ − 203
1250
+ − 204 Part of the configure output is a summary that looks something
+ − 205 like the following. (this summary is also available as the file
+ − 206 'Installation' in the top directory of your build tree, and via
+ − 207 the command 'M-x describe-installation RET').
428
+ − 208
1250
+ − 209 uname -a: Linux eicq 2.4.20 #1 Wed Dec 18 02:14:29 EST 2002 i586 unknown
428
+ − 210
1250
+ − 211 ./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'
+ − 212
+ − 213
+ − 214 XEmacs 21.5-b10 "burdock" (+CVS-20030131) configured for `i586-pc-linux'.
428
+ − 215
+ − 216
1250
+ − 217 Compilation / Installation:
+ − 218 Source code location: /usr/local/src/xemacs
+ − 219 Installation prefix: /usr/local
+ − 220 Additional prefixes: /usr/local/pgsql /usr/local/BerkeleyDB.4.1
+ − 221 Operating system description file: `s/linux.h'
+ − 222 Machine description file: `m/intel386.h'
+ − 223 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
+ − 224 Relocating allocator for buffers: no
+ − 225 GNU version of malloc: yes
+ − 226 - Using Doug Lea's new malloc from the GNU C Library.
428
+ − 227
1250
+ − 228 Window System:
+ − 229 Compiling in support for the X window system:
+ − 230 - X Windows headers location: /usr/X11/include
+ − 231 - X Windows libraries location: /usr/X11/lib
+ − 232 - Handling WM_COMMAND properly.
+ − 233 Compiling in support for the Athena widget set:
+ − 234 - Athena headers location: X11/neXtaw
+ − 235 - Athena library to link: neXtaw
+ − 236 Using Lucid menubars.
+ − 237 Using Athena scrollbars.
+ − 238 Using Athena dialog boxes.
+ − 239 Using Athena native widgets.
+ − 240
+ − 241 TTY:
428
+ − 242 Compiling in support for ncurses.
+ − 243 Compiling in support for GPM (General Purpose Mouse).
1250
+ − 244
+ − 245 Images:
+ − 246 Compiling in support for GIF images (builtin).
+ − 247 Compiling in support for XPM images.
+ − 248 Compiling in support for PNG images.
+ − 249 Compiling in support for JPEG images.
+ − 250 Compiling in support for TIFF images.
+ − 251 Compiling in support for X-Face message headers.
+ − 252
+ − 253 Sound:
+ − 254 Compiling in support for sound (native).
+ − 255
+ − 256 Databases:
+ − 257 Compiling in support for Berkeley database.
+ − 258 Compiling in support for PostgreSQL.
+ − 259 - Using PostgreSQL header file: libpq-fe.h
+ − 260 - Using PostgreSQL V7 bindings.
+ − 261
+ − 262 Internationalization:
+ − 263 Compiling in support for Mule (multi-lingual Emacs).
+ − 264 Compiling in support for XIM (X11R5+ I18N input method).
+ − 265 - Using raw Xlib to provide XIM support.
+ − 266 - Using XFontSet to provide bilingual menubar.
+ − 267
+ − 268 Mail:
+ − 269 Compiling in support for "dot-locking" mail spool file locking method.
+ − 270
+ − 271 Other Features:
+ − 272 Inhibiting IPv6 canonicalization at startup.
+ − 273 Compiling in support for dynamic shared object modules.
+ − 274 Using the new GC algorithms.
+ − 275 Using the new portable dumper.
+ − 276 Compiling in support for extra debugging code.
428
+ − 277 WARNING: ---------------------------------------------------------
+ − 278 WARNING: Compiling in support for runtime error checking.
+ − 279 WARNING: XEmacs will run noticeably more slowly as a result.
+ − 280 WARNING: Error checking is on by default for XEmacs beta releases.
+ − 281 WARNING: ---------------------------------------------------------
+ − 282
+ − 283
+ − 284
1250
+ − 285 Then...
+ − 286
+ − 287 $ make > ./beta.err 2>&1
+ − 288 $ make check > ./xemacs-make-check.err 2>&1
+ − 289
+ − 290 ...and you should have a working XEmacs.
428
+ − 291
+ − 292 After you have verified that you have a functional editor, fire up
+ − 293 your favorite mail program and send a build report to
1250
+ − 294 <xemacs-buildreports@xemacs.org>.
649
+ − 295
1250
+ − 296 Preferably this is best done from XEmacs, following these simple steps:
649
+ − 297
+ − 298 M-x customize-group RET build-report RET
+ − 299 M-x build-report RET
+ − 300
+ − 301 See also
1253
+ − 302 <http://www.xemacs.org/Releases/Public-21.2/tester.html#reporting>
649
+ − 303
+ − 304 If you create the report manually by other means, here is what the
+ − 305 build report should include:
428
+ − 306
+ − 307 1. Your hardware configuration (OS version, etc.)
+ − 308
+ − 309 2. Version numbers of software in use (X11 version, system library
+ − 310 versions if appropriate, graphics library versions if appropriate).
+ − 311 If you're on a system like Linux, include all the version numbers
+ − 312 you can because chances are it makes a difference.
+ − 313
+ − 314 3. The options given to configure
+ − 315
+ − 316 4. The configuration report illustrated above
+ − 317
+ − 318 For convenience all of the above items are placed in a file called
+ − 319 `Installation' in the top level build directory. They are also
+ − 320 available by performing M-x describe-installation inside XEmacs.
+ − 321
+ − 322 5. Any other unusual items you feel should be brought to the attention
+ − 323 of the developers.
+ − 324
743
+ − 325
1024
+ − 326 * Packages
+ − 327 ==========
+ − 328
+ − 329 [Note: these instructions have been partly updated, but not carefully
+ − 330 reviewed in some time. Caveat tester.]
+ − 331
+ − 332 Starting with XEmacs 21.1, much of the functionality of XEmacs has
+ − 333 been unbundled into "the packages." For more information about the
+ − 334 package system, see the Info nodes on Packages (in the XEmacs User
+ − 335 Manual) and on Packaging (in the Lisp Reference).
+ − 336
+ − 337 When bootstrapping XEmacs, you may need to manually install some
+ − 338 packages (at least xemacs-base and efs). These packages are available
1250
+ − 339 by FTP at <ftp://ftp.xemacs.org/pub/xemacs/packages/>.
1024
+ − 340
+ − 341 ** Binary package installation
+ − 342 ==============================
+ − 343
+ − 344 Prerequisite: XEmacs 21.0-b1.
+ − 345
+ − 346 Binary packages are complete entities that can be untarred at the top
+ − 347 level of an XEmacs package hierarchy and work at runtime. To install files
+ − 348 in this directory, run the command `M-x package-admin-add-binary-package'
+ − 349 and fill in appropriate values to the prompts.
+ − 350
+ − 351 ** Manual procedures for package management
+ − 352 ===========================================
+ − 353
+ − 354 Prerequisite: XEmacs 21.0
+ − 355
+ − 356 When adding and deleting files from a lisp directory the
+ − 357 auto-autoloads.el (global symbols) and custom-load.el (Customization
+ − 358 groups) must be kept in synch. Assuming one is manipulating a
+ − 359 directory called `lisp-utils', the command to rebuild the
+ − 360 auto-autoloads.el file is:
+ − 361
1250
+ − 362 xemacs -vanilla -batch \
+ − 363 -eval \("setq autoload-package-name \"lisp-utils\""\) \
+ − 364 -f batch-update-directory lisp-utils
1024
+ − 365
+ − 366 The command to rebuild the custom-load.el file is:
+ − 367
1250
+ − 368 xemacs -vanilla -batch -f Custom-make-dependencies lisp-utils
1024
+ − 369
1250
+ − 370 To byte-compile both of these files the command is:
1024
+ − 371
+ − 372 xemacs -vanilla -batch -f batch-byte-compile \
+ − 373 lisp-utils/auto-autoloads.el lisp-utils/custom-load.el
+ − 374
1250
+ − 375 Of course, being a beta tester, you'd be aware that it is much easier
+ − 376 to manage your XEmacs packages with PUI.
+ − 377
1024
+ − 378 ** Building XEmacs and XEmacs packages from scratch
+ − 379 ===================================================
+ − 380
1250
+ − 381 To build everything completely from scratch isn't hard, just time
+ − 382 consuming.
1024
+ − 383
1250
+ − 384 *** Step 1 - grab the sources (core and packages)
1024
+ − 385
1250
+ − 386 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs login
+ − 387 [password: "cvs" (sans quotes)]
1024
+ − 388
1301
+ − 389 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs co -d xemacs-21.5 xemacs
1024
+ − 390
1250
+ − 391 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs co packages
+ − 392
+ − 393 *** Step 2 - build XEmacs
1024
+ − 394
1250
+ − 395 $ cd xemacs-21.5
+ − 396 $ ./configure [options...]
+ − 397 $ make > ./beta.err 2>&1
+ − 398 $ make check > ./xemacs-make-check.err 2>&1
1024
+ − 399
1250
+ − 400 And optionally:
1024
+ − 401
1250
+ − 402 $ make install > ./xemacs-make-install.err 2>&1
+ − 403
+ − 404 *** Step 3 - build and install the packages
1024
+ − 405
1250
+ − 406 $ cd packages
+ − 407 $ cp Local.rules.template Local.rules
1024
+ − 408
1250
+ − 409 Then edit Local.rules to suit your needs/environment
+ − 410 see: (Info-goto-node "(xemacs)Local.rules file") for details about
+ − 411 this file.
1024
+ − 412
1250
+ − 413 And then:
1024
+ − 414
1250
+ − 415 $ make install
1024
+ − 416
+ − 417 * Improving XEmacs
743
+ − 418 =================
+ − 419
428
+ − 420 ** Creating patches for submission
+ − 421 ==================================
+ − 422
1044
+ − 423 All patches to XEmacs that are seriously proposed for inclusion (eg,
+ − 424 bug fixes) should be mailed to <xemacs-patches@xemacs.org>. Each
+ − 425 patch will be reviewed by the patches review board, and will be
743
+ − 426 acknowledged and added to the distribution, or rejected with an
+ − 427 explanation. Progress of the patch is tracked on the XEmacs Patches
1044
+ − 428 mailing list, which is open subscription. (If a patch is simply
+ − 429 intended to facilitate discussion, "I mean something that works like
1250
+ − 430 this but this is really rough", a Cc to XEmacs Patches is optional,
1044
+ − 431 but doesn't hurt.)
428
+ − 432
+ − 433 Patches to XEmacs Lisp packages should be sent to the maintainer of
+ − 434 the package. If the maintainer is listed as `XEmacs Development Team'
+ − 435 patches should be sent to <xemacs-patches@xemacs.org>.
+ − 436
+ − 437 Emailed patches should preferably be sent in MIME format and quoted
+ − 438 printable encoding (if necessary).
+ − 439
743
+ − 440 The simplest way to create well-formed patches is to use CVS and
+ − 441 Didier Verna's Patcher library (available as patcher.el in the
+ − 442 xemacs-devel package). Patcher is new and requires some setup, but
+ − 443 most of the core developers are now using it for their own patches.
+ − 444 Patcher also can be configured to create patches for several projects,
+ − 445 and recognize the project from the directory it is invoked in. This
+ − 446 makes it a useful general tool (as long as XEmacs-style patches are
+ − 447 accepted at your other projects, which is likely since they conform to
+ − 448 the GNU standards).
+ − 449
+ − 450 When making patches by hand, please use the `-u' option, or if your
+ − 451 diff doesn't support it, `-c'. Using ordinary (context-free) diffs
+ − 452 are notoriously prone to error, since line numbers tend to change when
428
+ − 453 others make changes to the same source file.
+ − 454
+ − 455 An example of the `diff' usage:
+ − 456
+ − 457 $ diff -u OLDFILE NEWFILE
+ − 458
+ − 459 -or-
+ − 460
+ − 461 $ diff -c OLDFILE NEWFILE
+ − 462
+ − 463 Also, it is helpful if you create the patch in the top level of the
+ − 464 XEmacs source directory:
+ − 465
+ − 466 $ cp -p lwlib/xlwmenu.c lwlib/xlwmenu.c.orig
+ − 467 hack, hack, hack....
+ − 468 $ diff -u lwlib/xlwmenu.c.orig lwlib/xlwmenu.c
+ − 469
+ − 470 Also note that if you cut & paste from an xterm to an XEmacs mail buffer
+ − 471 you will probably lose due to tab expansion. The best thing to do is
+ − 472 to use an XEmacs shell buffer to run the diff commands, or ...
+ − 473 M-x cd to the appropriate directory, and issue the command `C-u M-!' from
+ − 474 within XEmacs.
+ − 475
+ − 476 Patches should be as single-minded as possible. Mammoth patches can
+ − 477 be very difficult to place into the right slot. They are much easier
+ − 478 to deal with when broken down into functional or conceptual chunks.
+ − 479 The patches submitted by Kyle Jones and Hrvoje Niksic are stellar
1250
+ − 480 examples of how to "Do The Right Thing".
428
+ − 481
743
+ − 482 Each patch should be accompanied by an update to the appropriate
+ − 483 ChangeLog file. Guidelines for writing ChangeLog entries is governed
+ − 484 by the GNU coding standards. Please see
1250
+ − 485 <http://www.gnu.org/prep/standards_toc.html> [Change Logs section]
743
+ − 486 for details.
+ − 487
+ − 488 Do not submit context diffs (either -c or -u) of ChangeLogs. Because
+ − 489 of the "stack" nature of ChangeLogs (new entries are always pushed on
+ − 490 the top), context diffs will fail to apply more often than they
+ − 491 succeed. Simply cutting and pasting the entry from an Emacs buffer to
+ − 492 the mail buffer (beware of tab expansion!) is probably easiest. The
+ − 493 Patcher library also will set up your ChangeLogs for you, and copy
1250
+ − 494 them to the mail. Context-less unified diffs (-U 0) are also
+ − 495 acceptable.
428
+ − 496
743
+ − 497 *** Patch discussion etiquette
+ − 498 -------------------------------
428
+ − 499
743
+ − 500 If you intend a patch for _application_ to the sources as is, _always_
+ − 501 post it to xemacs-patches, even if there are minor points you would
+ − 502 like to have discussed by others. Not doing so will resulting in
+ − 503 patches getting "lost". If you expect that the patch will not be
+ − 504 acceptable, but are using it to stimulate discussion, then don't post
1250
+ − 505 to xemacs-patches. Intermediate cases are up to your judgment;
743
+ − 506 unless you're sure you'll follow up with a "real" patch, better to err
+ − 507 on the side of posting to xemacs-patches.
+ − 508
+ − 509 Discussion of the _content_ of the patch (ie responses to reviewer
+ − 510 comments beyond "that's right, ok, I'll do it your way") should _always_
1044
+ − 511 be posted to xemacs-beta or to xemacs-design. If you're not sure
+ − 512 which is more appropriate, send it to xemacs-beta. That is the most
+ − 513 widely read channel.
428
+ − 514
743
+ − 515 If discussion results in a bright idea and you come up with a new
+ − 516 patch, normally you should post it to both mailing lists. The people
+ − 517 discussing on XEmacs Beta will want to know the outcome of the thread,
+ − 518 and you need to submit to XEmacs Patches as the "list of record."
428
+ − 519
743
+ − 520 If the old patch has been applied to CVS, then just submit the new one
+ − 521 as usual. If it has not been applied, then it is best to submit a new
+ − 522 patch against CVS. If possible do this as a reply to the original
+ − 523 patch post, or something following it in the thread. (The point is to
+ − 524 get the original patch post's Message-ID in your References header.)
1044
+ − 525 In this case, also use the keyword SUPERSEDES in the Subject header to
743
+ − 526 indicate that the old patch is no longer valid, and that this one
+ − 527 replaces it.
+ − 528
+ − 529 These rules will result in a fair number of cross posts, but we don't
+ − 530 yet have a better way to handle that.
+ − 531
+ − 532 Note: Developers should never post to xemacs-patches unless there is a
+ − 533 patch in the post. We plan to enforce this with an automatic filter.
428
+ − 534
743
+ − 535 The exceptions are administrative. If you have commit authorization,
+ − 536 then post a short COMMIT notice to xemacs-patches when you commit to
+ − 537 CVS. Members of the Review Board will also post short notices of
+ − 538 administrative action (APPROVE, VETO, QUERY, etc) to xemacs-patches.
+ − 539
1024
+ − 540 ** Large contributions
+ − 541 ======================
743
+ − 542
1024
+ − 543 Perhaps you have a whole new mode, or a major synchronization with
+ − 544 upstream for a neglected package, or a synchronization with GNU Emacs
+ − 545 you would like to contribute. We welcome such contributions, but they
+ − 546 are likely to be relatively controversial, generate more comments and
+ − 547 requests for revision, and take longer to integrate. Please be
+ − 548 patient with the process.
428
+ − 549
1024
+ − 550 *** Updates to existing packages
+ − 551 --------------------------------
743
+ − 552
1024
+ − 553 If a package has gotten a bit out of date, or even started to bitrot,
+ − 554 we welcome patches to synchronize it with upstream/GNU Emacs versions.
+ − 555 Most packages end up varying somewhat from their GNU origins. See
+ − 556 "Syncing with GNU Emacs" for hints. Note that if you do a reasonably
+ − 557 large amount of syncing with GNU Emacs, you should log this in the
+ − 558 file itself as well as in the ChangeLog.
428
+ − 559
1024
+ − 560 If the package is important to you, please consider becoming the
+ − 561 maintainer. (See "New packages", below.)
428
+ − 562
1024
+ − 563 *** New packages
+ − 564 ----------------
428
+ − 565
1024
+ − 566 If you have a new mode or other large addition that does not require
+ − 567 changes to the core, please consider submitting it as a package, and
+ − 568 becoming the maintainer. You get direct commit privileges to the
+ − 569 repository for your package, "approval" privileges for your own
+ − 570 patches as well as third party patches to your package, and some
+ − 571 degree of veto power over patches you don't like. In return, you are
+ − 572 expected to maintain friendly liaison with the upstream developer (if
+ − 573 you aren't the upstream developer), keep watch on the XEmacs Patches
+ − 574 list for relevant patches, and be available by email to other
+ − 575 developers for discussion of changes that impact your package. It's
+ − 576 also a pretty standard route to the "core" development group, where we
+ − 577 have plenty of extra work waiting for volunteers.
428
+ − 578
1024
+ − 579 You don't have to become the maintainer, but it virtually ensures
+ − 580 rapid acceptance of the package.
428
+ − 581
1024
+ − 582 For help in creating new packages, see the (rather sparse) discussions
+ − 583 in the XEmacs User's Guide and the Lisp Reference Manual. The XEmacs
1301
+ − 584 Package Release Engineer (Ville Skytt� <scop@xemacs.org> is currently
1335
+ − 585 serving with Norbert Koch <viteno@xemacs.org> assisting; Steve
1301
+ − 586 Youngs <youngs@xemacs.org> and Stephen Turnbull <stephen@xemacs.org>
+ − 587 also can help) are the most likely sources of advice.
428
+ − 588
1024
+ − 589 *** Syncing with GNU Emacs
+ − 590 --------------------------
428
+ − 591
1024
+ − 592 Syncing with GNU Emacs is an important activity. Although each
+ − 593 version has its advantages and areas of concentration, it is very
+ − 594 desirable that common functionality share specifications and APIs.
+ − 595 When porting GNU code to XEmacs, the following points should be given
+ − 596 special attention:
428
+ − 597
1024
+ − 598 o Recent GNU Emacsen cannot be built without Mule, but XEmacs can.
+ − 599 Make sure your changes do not assume the presence of Mule.
428
+ − 600
1024
+ − 601 o GNU Emacs nomenclature often differs from that of XEmacs.
+ − 602 Sometimes syncing the names is desirable, other times not.
428
+ − 603
1024
+ − 604 o GNU Emacs functionality often differs from that of XEmacs.
+ − 605 Syncing functionality is often controversial.
428
+ − 606
1024
+ − 607 It is important that you let other developers know that
+ − 608 synchronization has taken place, to what degree, and when. For this
+ − 609 purpose, we use comments of the form
428
+ − 610
1024
+ − 611 /* Synched up with: FSF 21.3 by Stephen Turnbull */
428
+ − 612
1024
+ − 613 in the source file itself, as the last element of the prefatory
+ − 614 material (copyright notice and commentary). Obviously the comment
1301
+ − 615 marker needs to be changed to leading semicolons for Lisp, but
1024
+ − 616 otherwise the format is the same.
428
+ − 617
1024
+ − 618 Of course you should note syncing as the purpose in the ChangeLog,
+ − 619 too. But entries get buried deep in the ChangeLog file, and may even
+ − 620 get moved to a separate ChangeLog.OLD file for rarely synched files.
428
+ − 621
1024
+ − 622 Rather than dates we use the version of GNU Emacs to sync to. If the
+ − 623 synchronization is partial, add a new comment describing what has
+ − 624 actually been synched, leaving the description of the last full sync
+ − 625 in place. At each full sync, remove all previous synchronization
+ − 626 comments.
428
+ − 627
1024
+ − 628 This applies to Lisp that we have broken out into packages, but
+ − 629 remains in the GNU Emacs core, as well to core Lisp in XEmacs.
