Apply new glyph-image conventions for `ucs@*', `adobe-japan1-*',
[chise/xemacs-chise.git.1] / etc / BETA
1                                 -*- mode:outline -*-
2
3 * Introduction
4 ==============
5
6 You are running a potentially unstable version of XEmacs.  Please do
7 not report problems with Beta XEmacs to comp.emacs.xemacs.  Report
8 them to <xemacs-beta@xemacs.org>, preferably with 
9 'M-x report-xemacs-bug RET'. 
10
11 ** Mailing Lists
12 ================
13
14 *** XEmacs Beta Mailing List
15 ----------------------------
16
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
23 *** XEmacs Patches Mailing List
24 -------------------------------
25
26 XEmacs Patches records proposed changes to XEmacs, and their
27 disposition.  It is open subscription, and all patches that are
28 seriously proposed for inclusion in XEmacs should be posted here.  You
29 can follow progress of your patch by subscribing to the mailing list
30 or in the archives.
31
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 ----------------------
44
45 In the descriptions below, the word LIST (all uppercase) is a
46 variable.  Substitute "beta", "design", or "patches" as appropriate
47 (to get "xemacs-beta" as the mailbox for the XEmacs Beta mailing list,
48 or <http://www.xemacs.org/Lists/#xemacs-beta> for its URL).
49
50 The XEmacs mailing lists are managed by the Mailman mailing list
51 package, and the usual Mailman commands work.  Do not send mailing
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
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
60
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
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
69 interface at <http://www.xemacs.org/Lists/#xemacs-LIST>.
70
71 *** Subscribing by e-mail
72 -------------------------
73
74 Send an email message to <xemacs-LIST-request@xemacs.org> with
75 `subscribe' (without the quotes) as the BODY of the message.
76
77 *** Unsubscribing by e-mail
78 ---------------------------
79
80 Send an email message to <xemacs-LIST-request@xemacs.org> with
81 `unsubscribe' (without the quotes) as the BODY of the message.
82
83 ** Beta Release Schedule
84 ========================
85
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
101
102 ** Reporting Problems
103 =====================
104
105 The best way to get problems fixed in XEmacs is to submit good problem
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:
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
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.
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
144 available via CVS.  Please see
145
146             http://www.xemacs.org/Develop/cvsaccess.html
147
148 * Compiling Beta XEmacs
149 =======================
150
151 ** Building an XEmacs from patches
152 ==================================
153
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
160 shell command:
161
162 $ gunzip -c /tmp/xemacs-21.5.9-21.5.10.patch.gz | patch -p1
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
173 $ make beta > ./beta.err 2>&1
174 $ make check > ./xemacs-make-check.err 2>&1
175
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'
178
179 ** Building XEmacs from a full distribution
180 ===========================================
181
182 Locate a convenient place where you have at least 100MB of free space
183 and issue the command
184
185 $ gunzip -c /tmp/xemacs-21.5.10.tar.gz | tar xvf -
186
187 (or simply `tar zxvf /tmp/xemacs-21.5.10.tar.gz' if you use GNU tar).
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 \
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
203
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').
208
209 uname -a: Linux eicq 2.4.20 #1 Wed Dec 18 02:14:29 EST 2002 i586 unknown
210
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'.
215
216
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.
227
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:
242   Compiling in support for ncurses.
243   Compiling in support for GPM (General Purpose Mouse).
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.
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
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.
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
294 <xemacs-buildreports@xemacs.org>.
295
296 Preferably this is best done from XEmacs, following these simple steps:
297
298 M-x customize-group RET build-report RET
299 M-x build-report RET
300
301 See also
302 <http://www.xemacs.org/Releases/Public-21.2/tester.html#reporting>
303
304 If you create the report manually by other means, here is what the
305 build report should include:
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
325
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
339 by FTP at <ftp://ftp.xemacs.org/pub/xemacs/packages/>.
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
362 xemacs -vanilla -batch \
363   -eval \("setq autoload-package-name \"lisp-utils\""\) \
364   -f batch-update-directory lisp-utils
365
366 The command to rebuild the custom-load.el file is:
367
368 xemacs -vanilla -batch -f Custom-make-dependencies lisp-utils
369
370 To byte-compile both of these files the command is:
371
372 xemacs -vanilla -batch -f batch-byte-compile \
373         lisp-utils/auto-autoloads.el lisp-utils/custom-load.el
374
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
378 ** Building XEmacs and XEmacs packages from scratch
379 ===================================================
380
381 To build everything completely from scratch isn't hard, just time
382 consuming. 
383
384 *** Step 1 - grab the sources (core and packages)
385
386 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs login
387  [password: "cvs" (sans quotes)]
388
389 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs co -d xemacs-21.5 xemacs
390
391 $ cvs -d :pserver:cvs@cvs.xemacs.org:/pack/xemacscvs co packages
392
393 *** Step 2 - build XEmacs
394
395 $ cd xemacs-21.5
396 $ ./configure [options...]
397 $ make > ./beta.err 2>&1
398 $ make check > ./xemacs-make-check.err 2>&1
399
400 And optionally:
401
402 $ make install > ./xemacs-make-install.err 2>&1
403
404 *** Step 3 - build and install the packages
405
406 $ cd packages
407 $ cp Local.rules.template Local.rules
408
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.
412
413 And then:
414
415 $ make install
416
417 * Improving XEmacs
418 =================
419
420 ** Creating patches for submission
421 ==================================
422
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
426 acknowledged and added to the distribution, or rejected with an
427 explanation.  Progress of the patch is tracked on the XEmacs Patches
428 mailing list, which is open subscription.  (If a patch is simply
429 intended to facilitate discussion, "I mean something that works like
430 this but this is really rough", a Cc to XEmacs Patches is optional,
431 but doesn't hurt.)
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
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
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
480 examples of how to "Do The Right Thing".
481
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
485 <http://www.gnu.org/prep/standards_toc.html>   [Change Logs section]
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
494 them to the mail.  Context-less unified diffs (-U 0) are also
495 acceptable.
496
497 *** Patch discussion etiquette
498 -------------------------------
499
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
505 to xemacs-patches.  Intermediate cases are up to your judgment;
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_
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.
514
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."
519
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.)
525 In this case, also use the keyword SUPERSEDES in the Subject header to
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.
534
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
540 ** Large contributions
541 ======================
542
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.
549
550 *** Updates to existing packages
551 --------------------------------
552
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.
559
560 If the package is important to you, please consider becoming the
561 maintainer.  (See "New packages", below.)
562
563 *** New packages
564 ----------------
565
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.
578
579 You don't have to become the maintainer, but it virtually ensures
580 rapid acceptance of the package.
581
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
584 Package Release Engineer (Ville Skyttä <scop@xemacs.org> is currently
585 serving with Norbert Koch <viteno@xemacs.org> assisting; Steve
586 Youngs <youngs@xemacs.org> and Stephen Turnbull <stephen@xemacs.org>
587 also can help) are the most likely sources of advice.
588
589 *** Syncing with GNU Emacs
590 --------------------------
591
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:
597
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.
600
601   o GNU Emacs nomenclature often differs from that of XEmacs.
602     Sometimes syncing the names is desirable, other times not.
603
604   o GNU Emacs functionality often differs from that of XEmacs.
605     Syncing functionality is often controversial.
606
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
610
611 /* Synched up with: FSF 21.3 by Stephen Turnbull */
612
613 in the source file itself, as the last element of the prefatory
614 material (copyright notice and commentary).  Obviously the comment
615 marker needs to be changed to leading semicolons for Lisp, but
616 otherwise the format is the same.
617
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.
621
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.
627
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.