[chise/xemacs-chise.git.1] / etc / BETA

                                -*- mode:outline -*-

* Introduction
==============

You are running a potentially unstable version of XEmacs.  Please do
not report problems with Beta XEmacs to comp.emacs.xemacs.  Report
them to xemacs-beta@xemacs.org.

** Mailing Lists
================

*** XEmacs Beta Mailing List
----------------------------

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).

*** XEmacs Patches Mailing List
-------------------------------

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.

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.

*** 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 http://www.xemacs.org/Lists/#xemacs-beta 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 (xemacs-LIST@xemacs.org), always
send them to xemacs-LIST-request@xemacs.org.  If you have problems
with the list itself, they should be brought to the attention of the
XEmacs Mailing List manager <list-manager@xemacs.org> (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 http://www.xemacs.org/Lists/#xemacs-LIST.

*** Subscribing by e-mail
-------------------------

Send an email message to xemacs-LIST-request@xemacs.org with
`subscribe' (without the quotes) as the BODY of the message.

*** Unsubscribing by e-mail
---------------------------

Send an email message to xemacs-LIST-request@xemacs.org with
`unsubscribe' (without the quotes) as the BODY of the message.

** Beta Release Schedule
========================

Betas are now released rather sporadically.  We would like to achieve
a weekly release schedule, but personnel availability does not
permit.  For access to the most recent code, use CVS (see
http://www.xemacs.org/Develop/cvsaccess.html for more information).
If you have need for FTP access, 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:

1.  Do not submit C stack backtraces without line numbers.  Since it
    is possible to compile optimized with debug information with GCC
    it is never a good idea to compile XEmacs without the -g flag.
    XEmacs runs on a variety of platforms, and often it is not
    possible to recreate problems which afflict a specific platform.
    The line numbers in the C stack backtrace help isolate where the
    problem is actually occurring.
 
2.  Attempt to recreate the problem starting with an invocation of
    XEmacs with `xemacs -q -no-site-file -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 -q -no-site-file' 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
    screen dump and include that with the problem report.  The easiest
    way to get a screen dump is to use the xv program and its grab
    function.  Save the image as a GIF to keep bandwidth requirements
    down without loss of information.  MIME is the preferred method
    for making the image attachments.

** Getting the Source
=====================

In addition to the normal tar distribution, XEmacs source is now
available via CVS.  Please see

            http://www.xemacs.org/Develop/cvsaccess.html

* Compiling Beta XEmacs
=======================

** 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
shell command:

$ gunzip -c /tmp/xemacs-20.15-b10-20.15-b11.patch.gz | patch -p1

After patching, check to see that no patches were missed by doing
$ find . -name \*.rej -print

Any rejections should be treated as serious problems to be resolved
before building XEmacs.

After seeing that there were no rejections, issue the commands

$ ./config.status --recheck
$ make beta

and go play minesweep for a while on an older XEmacs while the binary
is rebuilt.

** 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 -

(or simply `tar zxvf /tmp/xemacs-20.15-b11.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
the following.  (In XEmacs 21.1 and later, 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.)

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'.

  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.
  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.
  WARNING: ---------------------------------------------------------
  WARNING: Compiling in support for runtime error checking.
  WARNING: XEmacs will run noticeably more slowly as a result.
  WARNING: Error checking is on by default for XEmacs beta releases.
  WARNING: ---------------------------------------------------------



Then type `make' 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.

Preferrably this is done from XEmacs, following these simple steps:

M-x customize-group RET build-report RET
M-x build-report RET

See also
http://www.xemacs.org/Releases/Public-21.2/tester.html#reporting

If you create the report manually by other means, here is what the
build report should include:

1. Your hardware configuration (OS version, etc.)

2. Version numbers of software in use (X11 version, system library
   versions if appropriate, graphics library versions if appropriate).
   If you're on a system like Linux, include all the version numbers
   you can because chances are it makes a difference.

3. The options given to configure

4. The configuration report illustrated above

   For convenience all of the above items are placed in a file called
   `Installation' in the top level build directory.  They are also
   available by performing M-x describe-installation inside XEmacs.

5. Any other unusual items you feel should be brought to the attention
   of the developers.


* Packages
==========

[Note: these instructions have been partly updated, but not carefully
reviewed in some time.  Caveat tester.]

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).

When bootstrapping XEmacs, you may need to manually install some
packages (at least xemacs-base and efs).  These packages are available
by FTP at ftp://ftp.xemacs.org/pub/xemacs/packages/.

** Binary package installation
==============================

Prerequisite:  XEmacs 21.0-b1.

Binary packages are complete entities that can be untarred at the top
level of an XEmacs package hierarchy and work at runtime.  To install files
in this directory, run the command `M-x package-admin-add-binary-package'
and fill in appropriate values to the prompts.

** Manual procedures for package management
===========================================

Prerequisite: XEmacs 21.0

When adding and deleting files from a lisp directory the
auto-autoloads.el (global symbols) and custom-load.el (Customization
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 -vanilla -batch -l autoload -f batch-update-directory lisp-utils

The command to rebuild the custom-load.el file is:

xemacs -vanilla -batch -l cus-dep -f Custom-make-dependencies lisp-utils

To bytecompile both of these files the command is:

xemacs -vanilla -batch -f batch-byte-compile \
        lisp-utils/auto-autoloads.el lisp-utils/custom-load.el

** 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).

*** Phase 1 -- Get a minimal XEmacs binary with mule to build the package
    lisp with.

**** Grab a mule-base tarball and install it into a newly created package
     directory.

**** Configure XEmacs with mule and a package-path including the
     directory created above.

**** Do a `make dist' to build an XEmacs binary.

*** Phase 2 -- Build and install the package lisp.

**** Modify XEmacs.rules for local paths and the XEmacs binary created in 
     Phase 1.

**** Do a make from the top level package lisp source directory.[1]

**** Do `make bindist's on all the packages you wish to install and
     remove the byproduct .tar.gz's.

*** Phase 3 -- If necessary, redump XEmacs
    with the packages that require dump-time support and install it.

**** Reconfigure without Mule if you don't wish a Mule-ish XEmacs, and
     rebuild XEmacs.

- or -

**** rm lib-src/DOC src/xemacs; make

**** Install or run in-place.

Note that this is in essence what `make all-elc' has always done.


* Improving XEmacs
=================

** Creating patches for submission
==================================

All patches to XEmacs that are seriously proposed for inclusion (eg,
bug fixes) should be mailed to <xemacs-patches@xemacs.org>.  Each
patch will be reviewed by the patches review board, and will be
acknowledged and added to the distribution, or rejected with an
explanation.  Progress of the patch is tracked on the XEmacs Patches
mailing list, which is open subscription.  (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 <xemacs-patches@xemacs.org>.

Emailed patches should preferably be sent in MIME format and quoted
printable encoding (if necessary).

The simplest way to create well-formed patches is to use CVS and
Didier Verna's Patcher library (available as patcher.el in the
xemacs-devel package).  Patcher is new and requires some setup, but
most of the core developers are now using it for their own patches.
Patcher also can be configured to create patches for several projects,
and recognize the project from the directory it is invoked in.  This
makes it a useful general tool (as long as XEmacs-style patches are
accepted at your other projects, which is likely since they conform to
the GNU standards).

When making patches by hand, please use the `-u' option, or if your
diff doesn't support it, `-c'.  Using ordinary (context-free) diffs
are notoriously prone to error, since line numbers tend to change when
others make changes to the same source file.

An example of the `diff' usage:

$ diff -u OLDFILE NEWFILE

-or-

$ diff -c OLDFILE NEWFILE

Also, it is helpful if you create the patch in the top level of the
XEmacs source directory:

$ cp -p lwlib/xlwmenu.c lwlib/xlwmenu.c.orig
  hack, hack, hack....
$ diff -u lwlib/xlwmenu.c.orig lwlib/xlwmenu.c

Also note that if you cut & paste from an xterm to an XEmacs mail buffer
you will probably lose due to tab expansion.  The best thing to do is
to use an XEmacs shell buffer to run the diff commands, or ...
M-x cd to the appropriate directory, and issue the command `C-u M-!' from
within XEmacs.

Patches should be as single-minded as possible.  Mammoth patches can
be very difficult to place into the right slot.  They are much easier
to deal with when broken down into functional or conceptual chunks.
The patches submitted by Kyle Jones and Hrvoje Niksic are stellar
examples of how to Do The Right Thing.

Each patch should be accompanied by an update to the appropriate
ChangeLog file.  Guidelines for writing ChangeLog entries is governed
by the GNU coding standards.  Please see
        http://www.gnu.org/prep/standards_toc.html   [Change Logs section]
for details.

Do not submit context diffs (either -c or -u) of ChangeLogs.  Because
of the "stack" nature of ChangeLogs (new entries are always pushed on
the top), context diffs will fail to apply more often than they
succeed.  Simply cutting and pasting the entry from an Emacs buffer to
the mail buffer (beware of tab expansion!) is probably easiest.  The
Patcher library also will set up your ChangeLogs for you, and copy
them to the mail.  Contextless unified diffs (-U 0) are also
acceptable but perhaps more trouble than they are worth.

*** Patch discussion etiquette
-------------------------------

If you intend a patch for _application_ to the sources as is, _always_
post it to xemacs-patches, even if there are minor points you would
like to have discussed by others.  Not doing so will resulting in
patches getting "lost".  If you expect that the patch will not be
acceptable, but are using it to stimulate discussion, then don't post
to xemacs-patches.  Intermediate cases are up to your judgement;
unless you're sure you'll follow up with a "real" patch, better to err
on the side of posting to xemacs-patches.

Discussion of the _content_ of the patch (ie responses to reviewer
comments beyond "that's right, ok, I'll do it your way") should _always_
be posted to xemacs-beta 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ä <ville.skytta@xemacs.org> is
currently serving with Peter Brown <rendhalver@users.sourceforge.net>
assisting; Steve Youngs <youngs@xemacs.org> and Stephen Turnbull
<stephen@xemacs.org> also can help) is the most likely source of advice.

*** Syncing with GNU Emacs
--------------------------

Syncing with GNU Emacs is an important activity.  Although each
version has its advantages and areas of concentration, it is very
desirable that common functionality share specifications and APIs.
When porting GNU code to XEmacs, the following points should be given
special attention:

  o Recent GNU Emacsen cannot be built without Mule, but XEmacs can.
    Make sure your changes do not assume the presence of Mule.

  o GNU Emacs nomenclature often differs from that of XEmacs.
    Sometimes syncing the names is desirable, other times not.

  o GNU Emacs functionality often differs from that of XEmacs.
    Syncing functionality is often controversial.

It is important that you let other developers know that
synchronization has taken place, to what degree, and when.  For this
purpose, we use comments of the form

/* Synched up with: FSF 21.3 by Stephen Turnbull */

in the source file itself, as the last element of the prefatory
material (copyright notice and commentary).  Obviously the comment
marker needs to be changed to leading semicolons for Lisp, but
otherwise the format is the same.

Of course you should note syncing as the purpose in the ChangeLog,
too.  But entries get buried deep in the ChangeLog file, and may even
get moved to a separate ChangeLog.OLD file for rarely synched files.

Rather than dates we use the version of GNU Emacs to sync to.  If the
synchronization is partial, add a new comment describing what has
actually been synched, leaving the description of the last full sync
in place.  At each full sync, remove all previous synchronization
comments.

This applies to Lisp that we have broken out into packages, but
remains in the GNU Emacs core, as well to core Lisp in XEmacs.