Initial Commit

[packages] / xemacs-packages / general-docs / texi / xemacs / xemacs-devguide.texi

\input texinfo   @c -*-texinfo-*-
@c $Id: xemacs-devguide.texi,v 1.7 2009-02-24 09:59:13 stephent Exp $
@c Generate HTML with:
@c   (shell-command "texi2html -number -monolithic xemacs-devguide.texi" nil)
@c
@c %**start of header
@setfilename ../../info/xemacs-devguide.info
@settitle xemacs-devguide
@c %**end of header

@c Developer's Guide variables.
@set DEVGUIDE @cite{XEmacs Developer's Guide}
@set EDITION 0.8.1
@set UPDATED 2015-12-03
@set UPDATE-MONTH December, 2015

@c Other variables.
@set XEMACSORG XEmacs.ORG
@set PROJECT XEmacs Project
@set HOMEPAGE @uref{http://www.xemacs.org/,XEmacs Project Website}
@set BOARD XEmacs Review Board
@set C-E-X the @i{comp.emacs.xemacs} Usenet newsgroup
@set ANNOUNCE-LIST the @email{xemacs-announce@@xemacs.org,XEmacs Announcements} mailing list
@set BETA-LIST the @email{xemacs-beta@@xemacs.org,XEmacs Beta} mailing list
@c xemacs-design is currently not operative; substitute xemacs-beta
@set DESIGN-LIST the @email{xemacs-design@@xemacs.org,XEmacs Design} mailing list
@set REVIEW-LIST the @email{xemacs-review@@xemacs.org,XEmacs Review} mailing list
@set PATCHES-LIST the @email{xemacs-patches@@xemacs.org,XEmacs Patches} mailing list
@set BUILDREPORTS-LIST the @email{xemacs-buildreports@@xemacs.org,XEmacs Build Reports} mailing list

@copying
This is Edition @value{EDITION} of the @value{DEVGUIDE},
last updated @value{UPDATED}.

Copyright @copyright{} 2000, 2001, 2002, 2003, 2004 Bill Wohler

Copyright @copyright{} 2005, 2007 Free Software Foundation

@quotation
The @value{DEVGUIDE} is free documentation; you can
redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation; either
version 2, or (at your option) any later version.

The @value{DEVGUIDE} is distributed in the hope that it
will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
the GNU General Public License for more details.

The GNU GENERAL PUBLIC LICENSE appears as an appendix to this
document. You may also request a copy by writing to the Free
Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.
@end quotation
@end copying

@setchapternewpage odd

@dircategory XEmacs Editor
@direntry
* XEmacs Developer's Guide: (xemacs-devguide).  DRAFT.
@end direntry

@titlepage
@title The XEmacs Developer's Guide
@subtitle Edition @value{EDITION}
@subtitle @value{UPDATE-MONTH}
@author Stephen J. Turnbull

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Acknowledgments, (dir), (dir)
@top The XEmacs Developers Guide
@insertcopying
@end ifnottex

@cartouche

@strong{This document is under development.}  The current version
contains a lot of text drawn from the @emph{MH-E Developers Guide} which
is inapplicable to the @value{PROJECT}.  Those parts which have been
adjusted to reflect @value{PROJECT} practice are based on the opinions
of the author(s) as to best practice and desirable policy, and
@strong{are not yet approved as official policy}.

@end cartouche

@menu
* Acknowledgments::             
* Introduction::                
* Philosophy::                  
* The Work Roles::              
* The Work Flow::               
* XEmacs Resources on the Internet::  
* Copying::
* Nodes borrowed from other projects not adapted to XEmacs::
* Index::                       

@detailmenu
 --- The Detailed Node Listing ---

People and the Project

* Beta Tester::                 
* Committer::                   
* XEmacs Package Maintainer::   
* XEmacs Reviewer::             
* Meta-Maintainer::             
* Release Engineer::            
* Jobs List::                   

Committer

* Commit Access::               
* Committer Welcome Message::   

XEmacs Package Maintainer

* The Package Maintainer Role::
* Advice to Package Maintainers::

XEmacs Reviewer

* Appointing New Reviewers::    
* Welcoming New Reviewers::     

The Life Cycle of a Patch

* About Copyright Assignment::  
* Scratching That Itch::        
* Get the Sources::             
* Write Low-Profile Code::      
* Test Your Changes::           
* Add a ChangeLog Entry::       
* Create the Patch::            
* Submit the Patch::            
* Patch Review::                
* Committing the Patch::        
* Dispute Resolution::          

Add a ChangeLog Entry

* ChangeLogs::                  
* Log Messages::                

Submit the Patch

* Optional Alternate Procedure for Reviewers::  

Patch Review

* Commit-and-Review::           

Committing the Patch

* Proposed Alternative Procedure::  

XEmacs Resources on the Internet

* Project Website::             
* Mercurial Repository::              
* comp.emacs.xemacs::           
* xemacs-beta::                 
* xemacs-design::               
* xemacs-patches::              
* xemacs-mule::                 
* xemacs-winnt::                

Nodes borrowed from other projects, not adapted to XEmacs

* Support Requests::            
* Bugs::                        
* Feature Requests::            
* Patch Queue::                 
* File Releases::               
* News::                        
* Surveys::                     
* Free Software Directories::   

Bugs

* Category::                    
* Status::                      
* Group::                       
* Resolution::                  

File Releases

* Release Schedule::            
* Release Prerequisites::       
* Updating NEWS::               
* Updating README::             
* Updating Version Number::     
* Updating ChangeLogs::         
* Tagging Releases::            
* Creating Tarballs::           
* Creating @value{XEMACSORG} Releases::  
* Updating the Tracker::        
* Announce the Release::        
* Updating the Emacs Repository::  
* Updating the Debian Package::  
* Updating the XEmacs Package::  
* Updating the Online Documentation::  
* Updating the Free Software Directories::  
* After the Release::           

@end detailmenu
@end menu

@node Acknowledgments, Introduction, Top, Top
@chapter Acknowledgments

Special thanks go to Bill Wohler, whose @emph{MH-E Developers Guide}
formed the framework for this document, and contributed a lot of text as
well, for permission to redistribute the derived work under the GNU
General Public License.

The best practices exemplified by Martin Buchholz and Vin Shelton are
the primary reference for the section on release engineering of the core
XEmacs distribution.



@node Introduction, Philosophy, Acknowledgments, Top
@chapter Introduction

@cindex Introduction
@cindex @value{XEMACSORG}

So, you want to be an XEmacs developer!  You've already taken the
essential step by showing enough interest to read this document.  This
document describes other steps you may wish to take to participate more
effectively.  First, it describes the philosophy of the development team.
A section for each resource in the @value{PROJECT} that
developers may want to use or need to change follows.

In other words, this is the single sheet of music that all the XEmacs
developers are playing.

Note that it is about project organization and administration, not about
the code base.  For coding standards and techniques, XEmacs has a
separate manual, @ref{Top, The XEmacs Internals Manual, , internals}.

@cindex mailing lists, xemacs-design
@cindex xemacs-design

And remember, this is your document.  If you think something is bogus,
start a movement on @value{BETA-LIST}.  One of the tenets of the
philosophy is rough consensus.  If you can get a rough consensus to agree
with your point of view, then the document shall be changed accordingly.

@cartouche

@strong{This document is under development.}  The current version
contains a lot of text drawn from the @emph{MH-E Developers Guide} which
is inapplicable to the @value{PROJECT}.  Those parts which have been
adjusted to reflect @value{PROJECT} practice are based on the opinions
of Stephen Turnbull as to best practice and desirable policy, and
@strong{are not yet approved as official policy}.

Feel free to submit patches to @value{PATCHES-LIST}.  Please try to
review and edit a whole node at a time.  They're short; it's not that
great a burden.

@end cartouche



@node Philosophy, The Work Roles, Introduction, Top
@chapter Philosophy

@cindex Philosophy

@strong{This node has a fair amount of content almost
unchanged from the @emph{MH-E Developers Guide}, and is not fully
representative of the @value{PROJECT}.  However, everything here has
been espoused by XEmacs developers at one time or another.}

This chapter discusses the philosophy and principles of the XEmacs
project.  The first section covers our coding philosophy, while the
second section summarizes the principles of the team that have evolved
over time.

@heading Code

The core philosophies of the XEmacs project regarding the code are as
follows:

@enumerate
@item
Keep the C code fast.

@item
Refrain from adding lots of code to the C codebase that would be better
served with Lisp.

@item
XEmacs is a cross-platform application.  Features should work on all
platforms.

@item
XEmacs should be easy to use out-of-the-box for new users.
@end enumerate

@cindex customize
We should get as much mileage out of @code{customize} as we can to
reduce the amount of code that users have to write.

XEmacs at any time has a @emph{stable} branch and uses the @emph{trunk}
for development.  We do not freeze the trunk, except for the short
period of time needed to create a consistent release branch.  The
release branch in principle should only be changed for bug fixes.  (In
the past this principle has been honored as much in the breach as in the
observance; nevertheless, it's a good starting point.)

A change in the major version number indicates a pervasive change
affecting all users.  For example, the introduction of Mule in version
20, the extensive use of the package system in 21, and Unicode support
is planned for 22.  A change in the minor version number reflects addition of
features, and accompanies an initial public release.  A change in the
patchlevel reflects bugfix releases of the stable branch, while on the
trunk patchlevels are fairly arbitrary, reflecting regular beta
releases.

The stable branch has a single gatekeeper, the listed maintainer.
Changes are made only by the maintainer, or at his convenience with
explicit authorization.  Any XEmacs reviewer may make or authorize
changes to the trunk.  Having commit privileges does @emph{not}
authorize changes; commit privileges are for the convenience of the
project and of regular contributors, but do not imply a direct say in
decisions.  Conversely, we are always looking for new reviewers; the
review board is self-maintaining, but not closed.

Individual packages, like the stable branch, may have a listed
maintainer.  In those cases, the listed maintainer is the gatekeeper.
Please ask before committing to a package with a listed maintainer.
Many, but not all, will be happy to let you do so.

@heading Guiding Principles

The guiding principles of the XEmacs developers are:

@enumerate 1
@item
We all are scratching an itch on this project.  We respect each others'
goals, which are quite varied.

@item
Using vulgar language towards our users and/or developers is
unacceptable.

@item
The team makes decisions by consensus through articulated arguments.
If one wants to express an opinion, they do it by presenting evidence
to support their claim in a respectful way, and not by insulting
others' points of view.  Where consensus seems hard to achieve, what we
try first may be decided by a vote in the Review Board.

@item
We are all committed to a high-quality product.  We have no artificial
deadlines, so if it takes an extra iteration or two to find the
optimal solution to a problem, then we do it.

@item
We believe in collective ownership.  We keep our egos in check and say
"Thank you" to a colleague when he rewrites our code.  He'll thank you
when you fix his.

@item
Finally, we're here to have fun.
@end enumerate

@heading Coding Conventions

Coding conventions are described in detail elsewhere.
@c #### Make this xref more precise.
@xref{Top, Internals Manual, , internals}.

@c #### Move these somewhere more appropriate
Here are a few additional references that you might want to check out.

@cindex Coding Conventions
@cindex Emacs Lisp Coding Conventions
@cindex Library Headers
@cindex Conventions, verification
@cindex Verification, conventions
@findex @code{lm-verify}
@findex @code{checkdoc}
@cindex @file{lisp-mnt}

The (GNU) Emacs Lisp Manual
@ifnothtml
@ref{Tips, Tips and Conventions, , elisp}.
@end ifnothtml
@ifhtml
@uref{http://www.sunsite.ualberta.ca/Documentation/Gnu/emacs-lisp-ref-21-2.7/html_node/elisp_708.html,
Tips and Conventions}.
@end ifhtml

@strong{Please ensure that the copyright notice of every file accurately
reflects your contribution, whether you have assigned your copyright to
the FSF or not.  This will aid future project admins greatly if there
ever is a merger of XEmacs with Emacs.}  ``Accurately reflects'' means
that if you have not assigned your contribution, @emph{your name} should
appear in a copyright notice, along with an accurate list of the years
in which your contributions were made.  If you have assigned your
contribution, you should list the FSF (or other assignee) as copyright
holder, and make sure that the list of years is appropriately updated.
In both cases, an accurate ChangeLog detailing your changes (file and
function) should accompany the patch.

You @strong{must} reference the GPL correctly in every file you change.
That is the law, in the U.S. and in all countries we know about.  (If a
file is not under the GPL, please report it as a possible bug.  Some
files are not, but it's worth checking.  If you wish to contribute a
whole, new file under a non-GPL but GPL-compatible license, that is also
possible.  What you may not do is remove or alter others' copyright
attributions, or any license notice that is present.)

Manuals must also follow these rules, except that for historical reasons
they have various different licenses.  @emph{Be careful}: it is
typically @strong{not} permissible to mix excerpts from different
documents with each other, or with XEmacs code, unless they have
@emph{identical} licenses.  In particular, the XEmacs Texinfo manuals
(the @emph{XEmacs User's Guide}, the @emph{XEmacs Lisp Reference}, and
the @emph{XEmacs Internals Manual}) have a unique license which is not
the GPL or the GFDL, and is incompatible with both.

All code and data files must be licensed under the GPL (or a compatible
license) so that they can be added to XEmacs, and others may modify them.

Documentation files must be licensed under an approved free license or
an OSI-approved open source license.  Where possible, GPL-compatible
licenses are preferred.  If at all possible, avoid the GNU Free
Documentation License, because it is @emph{incompatible with the GPL},
implying that text cannot be copied freely between docstrings and the
Texinfo manual, except by the copyright holder.

The @uref{http://www.gnu.org/prep/standards.html, GNU
Coding Conventions} is required reading.  Note that XEmacs has its own
slightly different, version.  @xref{Top, Coding Standards, ,standards}.

Before checking in files, load @file{lisp-mnt} into Emacs, and run
@code{lm-verify} within the lisp file you are editing to ensure that
all of the fields described in
@ifnothtml
@ref{Library Headers, , , elisp},
@end ifnothtml
@ifhtml
@uref{http://www.sunsite.ualberta.ca/Documentation/Gnu/emacs-lisp-ref-21-2.7/html_node/elisp_713.html,
Library Headers}
@end ifhtml
are present.  The @code{checkdoc} function should be run before check-ins
as well.  All errors must be fixed.

You should also @emph{read the comments} in the @file{lisp-mnt} library
source.

Any steps needed to build or disseminate releases should be found in
Makefiles (or in this document).  In other words, there is to be no magic
stored only in someone's head.


@node The Work Roles, The Work Flow, Philosophy, Top
@chapter The Work Roles

On the one hand, ``open source'' means that you are free to take the
existing program, make it into whatever you want, and nobody will stop
you.  On the other hand, ``open source'' means that you are free to
share the program with anybody you like, and even people you don't like!
People being what they are, the detailed goals differ from one to
another, and they end up in conflicts between one person's goals and
another's.

Allowing people to fill roles that suit them, and creating a work flow
that lets them share the products of their work without getting in each
others' way, are the foundations of the project.

@heading People and the Project

@cindex Definitions
@cindex developer
@cindex contributor

A @dfn{developer} or @dfn{contributor} is anyone who wants to
participate in improving XEmacs.  Presumably you do, because you're
reading this @emph{Guide}.  Well then---presto-chango! you're an
XEmacs developer.

That doesn't mean that some developers don't have more privileges than
others, that all contributions are accepted, or that some contributions
aren't bigger than others.  What it means is that the @value{PROJECT} is
intended to facilitate individual contributions and cooperation among
contributors.  It means that in the @value{PROJECT} we don't make a
sharp distinction between ``users'' and ``developers.''  Some important
contributors never submit code to the project; they simply
participate in the newsgroups and mailing lists, giving advice based on
their experience to other users.

Here are some of the better defined roles.  Most are defined by
reference to @value{PROJECT} resources.

@table @dfn
@item Developer
@itemx Contributor
You.  Me.  Generally, anybody who wants to help improve XEmacs.
@xref{The Work Flow}.

@item User
You.  Me.  Generally, anybody whose needs are being served by XEmacs.
Specifically, someone who can tell us how to do it better.  Often,
someone who advises other users on mailing lists or Usenet.
@xref{XEmacs Resources on the Internet}.

@item Beta tester
A user currently not active as a code contributor, but willing to
reinstall XEmacs or its packages regularly, and report any problems.
Should participate in @value{BETA-LIST}.  @xref{xemacs-beta}.

@item Committer
A developer with write access to the XEmacs repositories, which may be
restricted to specified modules.  @xref{Committer}.  Should participate
in @value{BETA-LIST} @ref{xemacs-beta}, and @value{PATCHES-LIST}
@ref{xemacs-patches}.

@item Package maintainer
A committer with responsibility for integrating a separately maintained
component, containing a set of optional libraries, with XEmacs.  The component
often constitutes a well-defined application, such as an MUA.
@xref{XEmacs Package Maintainer}.

@item Reviewer
A developer who may authorize developers, including himself, to write to
the XEmacs repositories.  @xref{XEmacs Reviewer}.  Should participate
in @value{BETA-LIST} @ref{xemacs-beta}, @value{PATCHES-LIST}
@ref{xemacs-patches}, and @value{REVIEW-LIST}
@ref{xemacs-review}.

@item XEmacs Review Board
The reviewers as a group, responsible for delegating access to
@value{PROJECT} resources to developers.  A self-selecting cabal.  The
current members are noted on the
@uref{http://www.xemacs.org/Develop/jobs.html,@emph{Jobs List}}.
@xref{Jobs List}.

@item Chairman of the Board
@itemx CEO
@itemx Maintainer
@itemx Benevolent Dictator for Life
Call it what you like, we don't have one any more, by deliberate choice.

@item Meta-maintainer
@itemx Mr. XEmacs
The reviewer responsible for trying to keep track of what isn't getting
done, and finding someone to do it.  The latter title allows him to tell
his mother how important he is.  More seriously, the meta-maintainer
often functions as a spokesman for the Board or the project as a whole.
Should be highly visible on @value{C-E-X} @ref{comp.emacs.xemacs} and
@value{BETA-LIST} @ref{xemacs-beta}.

@item Release engineer
@itemx Stable release engineer
@itemx Package release engineer
Responsible for the quality control and adminstrative details of
distributing some coherent package of functionality.  The @dfn{stable
release engineer} manages the core distribution, including the build
infrastructure, the Lisp and display engine, and the functions typical
of a programmer's editor.  The @dfn{package
release engineer} manages the various unbundled applications, the
build infrastructure, and the network-based download and install
functionality for them.  Must participate in @value{PATCHES-LIST}
@ref{xemacs-patches}.
@c #### Write nodes for these posts!

@item Postmaster
@itemx Webmaster
@itemx Repository Manager
Administrators of the various Internet-based services important to
XEmacs users and developers.
@c #### Write nodes for these posts!

@item Miscellaneous
The @emph{Jobs List} describes a number of other idiosyncratic positions
and tasks in the @value{PROJECT}.  It also lists the current members of
the @value{BOARD}.  @xref{Jobs List}.  The most recent version can be
found @uref{http://www.xemacs.org/Develop/jobs.html,on the website}.
@end table

@menu
* Beta Tester::                 
* Committer::                   
* XEmacs Package Maintainer::   
* XEmacs Reviewer::             
* Meta-Maintainer::             
* Release Engineer::            
* Jobs List::                   
@end menu



@node Beta Tester, Committer, The Work Roles, The Work Roles
@section Beta Tester

@cindex beta tester
@cindex tester, beta
@cindex xemacs-beta mailing list
@cindex mailing list, xemacs-beta
@cindex xemacs-buildreports mailing list
@cindex mailing list, xemacs-buildreports
@cindex xemacs-design mailing list
@cindex mailing list, xemacs-design
@findex report-xemacs-bug
@findex build-report

An extremely important role is that of @dfn{beta tester}.  Since the
XEmacs repositories are open for anonymous read access, beta testers
do not get special access to unpublished code.  Rather, beta testers
@c #### need @xrefs for bug and build reports
contribute by submitting bug reports on problems, and build reports to
give the community information about the variety of platforms and
features XEmacs is being configured for.  Bug reports are submitted to
@value{BETA-LIST}, preferably via @kbd{M-x report-xemacs-bug RET}.
@value{BETA-LIST} is also the channel to lobby for their favorite new
features.
Build reports are submitted to @value{BUILDREPORTS-LIST}
via the @kbd{M-x build-report RET} utility.

However, for those who do wish to make contributions to the collection
of bytes that we call ``XEmacs'', there are a number of formal roles,
with powers and privileges that make it easier to make them.



@node Committer, XEmacs Package Maintainer, Beta Tester, The Work Roles
@section Committer

@cindex committer

@c MH-E says that committers may be _assigned_ bugs

A @dfn{committer} is one who is authorized to check in approved changes
into the source repository, including changes to private branches they may
maintain.  Note that, in contrast to the use of this term on many
projects, being a committer is simply an administrative convenience;
committers must wait for approval to check in changes.
Developers who do not have repository write access contribute by
submitting patches to @value{PATCHES-LIST}.

Commit access is generally given to those who have submitted several
good patches, to ``well-known'' developers on request, and to XEmacs
package maintainers.

@menu
* Commit Access::               
* Committer Welcome Message::   
@end menu



@node Commit Access, Committer Welcome Message, Committer, Committer
@subsection Commit Access

@cindex commit access
@cindex bitbucket.org committer accounts

There are a few minor prerequisites to get out of the way.  The first is
to get an account on @i{bitbucket.org} so that you can access the
Mercurial repositories for XEmacs core code and packages.
The second is to
@uref{http://www.xemacs.org/Lists/#xemacs-beta, subscribe to
the XEmacs Beta mailing list}.

@cindex XEmacs User's Guide
@cindex manuals, XEmacs
@cindex XEmacs Lisp Reference
@cindex manuals, XEmacs Lisp

@c #### fix these urefs!!
Developers should be familiar with the
@uref{http://www.xemacs.org/Documentation/21.5/html/,XEmacs Lisp Manual}
@ifnottex
@xref{Top, XEmacs Lisp Reference, , lispref}.
@end ifnottex
as well as the
@uref{http://www.xemacs.org/Documentation/21.5/html/,XEmacs Manual}.
@ifnottex
@xref{Top, XEmacs User's Guide, , xemacs}.
@end ifnottex

@cindex xemacs-design mailing list
@cindex mailing lists, xemacs-design
@cindex committer
@cindex bitbucket.org

If you think that you may contribute enough to want write access to the source
repositories, request access from the @email{mike@@xemacs.org,Mercurial
Administrator} and get an account on @i{bitbucket.org}.
Generally speaking, if you have contributed to the
@value{PROJECT} mailing lists and @i{comp.emacs.xemacs} newsgroup over
the years, you will be given write privileges within a few days.  If you
are new, you may need to find a sponsor on the @value{BOARD} to vouch
for you.

@cindex pictures of developers
@cindex developers, pictures
@cindex information about developers
@cindex developers, information about

On a less serious note, the @code{about-xemacs} command gives
information, including photos, about developers past and present.
Submit a patch to @file{lisp/about.el} and an image that represents you
(as both a monochrome PNG and a color PNG) to @value{PATCHES-LIST}.



@node Committer Welcome Message,  , Commit Access, Committer
@subsection Committer Welcome Message
@c #### The information in this message should be parsed out into Work Flow.

@cindex committers, welcoming
@cindex welcoming committers

Here's a typical welcome message for a new package maintainer.  The
changes appropriate to a generic committer should be pretty obvious.

@display
To: "Newbert Committer, redtape Package Maintainer" <newbie@@xemacs.org>
CC: XEmacs Review Board <xemacs-review@@xemacs.org>,
    newbert.committer@@xemacs.org, newb.committer@@xemacs.org,
    newbie@@general-conglobulation.com
Subject: Welcome to The XEmacs Development Team.

Hi Newbie!

On behalf of the XEmacs Review Board, I'd like to welcome you to the
team as our new redtape maintainer.  We really appreciate the time and
effort you put into redtape and we'd like to thank you very much for
taking on this important role.

The first thing that you should notice is that you have received 4
copies of this message.  One to your existing email address, and one
each to your 3 new xemacs.org addresses.  You can use the xemacs.org
addresses for any XEmacs related purpose.  Please note that this is
neither a requirement or a restriction.  Some of our developers rarely
use their xemacs.org email address, while others use theirs for most
things.

At this point, Newbie, I'd suggest that you subscribe to a couple of
our mailing lists, if you haven't already done so.

        xemacs-beta (for all kinds of code discussion)
        xemacs-patches (this is where all patches are sent)

You can subscribe to these (and the other XEmacs mailing lists) at
<http://www.xemacs.org/Lists/>.  Or via email, to:

        xemacs-beta-request@@xemacs.org
        xemacs-patches-request@@xemacs.org

With "subscribe" (sans quotes) in the body of the emails.

It also may be worth your while to monitor comp.emacs.xemacs if you
have Usenet access.

Here are a few guidelines that should make things run fairly smoothly
for all those involved.  See the section ``XEmacs Package Maintainer''
in the XEmacs Developer Guide for additional information and tips.

Building
========

For a quick start to building packages, see INSTALL under the packages/
dir where you set up a local source tree.

Patches
=======

All changes must be documented by a patch sent to the xemacs-patches
mailing list.  The patch must be accompanied by a ChangeLog.  The
appropriate format is that generated by 'M-x add-change-log-entry'.
This convenient function also automatically determines file and
function containing the change, finds the appropriate ChangeLog
file, and formats the entry for you in the standard style.

Patches must be context diffs, preferably in diff -u format.
ChangeLogs should be in plain text or diff -U 0 format.  Documentation
is being prepared and will be available under
<http://www.xemacs.org/Develop/>.

One advantage of having all changes documented on xemacs-patches is
that of the "many eyes" principle.  Everyone on the XEmacs Review Board
actively monitors the xemacs-patches mailing list and will generally
look over any patch that falls into their area of expertise.  We've
caught many, otherwise overlooked, bugs simply because there has been
another set of eyes look at a patch.

As the maintainer of redtape, Newbie, any patches that you submit for
redtape are automatically pre-approved.  And you are the final
authority on any patches submitted against the redtape package, which also
includes patches from the XEmacs core developers.

Basically what I'm saying, Newbie, is that it is your code and you
shouldn't need our permission to make changes to it.  It's up to us to
look at your patches and yell if we think there is something wrong.
Be aware though, that the XEmacs Packages Release Manager is the final
authority on packaging infrastructure.  And it is XEmacs policy to
respect the wishes of the upstream maintainer, whether that is you or
some other party.

As the XEmacs Packages Release Manager, I'd like to add a couple of
things here:

        1) The packages repository is a "stable" branch, please
           do all that you can to keep it that way.

        2) In the Makefile you'll see "VERSION=" and
           "AUTHOR_VERSION=", please don't ever alter the former.  We
           do that as part of the package release process.

        3) When you update redtape on Bitbucket it'd be great if you could
           either drop me a quick email or post to xemacs-beta saying
           that redtape is ready for release.

Here's a brief rundown of how a package gets released:
-----------------------------------------------------
You
        - hack hack hack 
        - hg diff > cool-new-patch.diff
        - submit to xemacs-patches
        - unless there are objections, or if it's "obviously correct",
          commit and push to Bitbucket

Us
        - hg pull -u
        - build new version of redtape
        - upload to the "Pre-Release" directory of ftp.xemacs.org
        - announce release on xemacs-beta
        - time passes (no complaints about buggy redtape package)
        - move redtape package to the main packages directory on FTP site
        - announce release on xemacs-announce (which goes to
          xemacs-beta and comp.emacs.xemacs)

I think that fairly well covers most things, the only other thing I'd
like to mention is:  Have fun!  And don't restrict your involvement to
just redtape, if you notice anything else that could do with some help,
jump right in.

Once again, Newbie, thank you for taking on this very important role
for us.  And welcome to the Team!

Oldbert Reviewer,
XEmacs Package Release Manager.
@end display




@node XEmacs Package Maintainer, XEmacs Reviewer, Committer, The Work Roles
@section XEmacs Package Maintainer

@cindex XEmacs package maintainer
@cindex maintainer, XEmacs package
@cindex upstream maintainer
@cindex maintainer, upstream

A special kind of committer is the @dfn{XEmacs package maintainer}.
Much Emacs functionality comes in the form of add-on Lisp libraries.
Starting with XEmacs 20.4, most applications were unbundled from XEmacs,
and are now separately maintained, with their own release cycles, and
often separate development organizations.  An @dfn{XEmacs package
maintainer} is responsible for maintenance of the infrastructure
required to seamlessly integrate one or more libraries into XEmacs and
provide for convenient distribution and administration of the package by
users.

An XEmacs package maintainer approves patches for the package he
maintains, just as reviewers do for the rest of the code base.
@xref{XEmacs Reviewer}.  Only in rare cases (such as bugs causing data
loss or affecting security or stability of XEmacs) should reviewers,
other than the XEmacs Package Release Engineer, approve patches to
packages which have a designated maintainer.  Instead, they should
@samp{RECOMMEND} patches that they like.  @xref{Patch Review}.

In other words, each unbundled package, in principle, has a separate
development organization.  It may be hosted by the @value{PROJECT}, or
it may have its own resources.  A package's XEmacs maintainer may be an
XEmacs developer, the upstream maintainer of the Lisp libraries, or a
liaison drawn from either project.  Once the appointment is approved by
the upstream maintainer and the XEmacs Review Board, the XEmacs package
maintainer is given commit access restricted to the package's
repository, which is a subdirectory of the XEmacs packages repository.

XEmacs package maintainers are @emph{not} responsible for the
administrative aspects of releasing an XEmacs package of their
application; this work is done by the XEmacs Package Release Engineer.
Of course the package maintainer does have control over the decision to
release.

@menu
* The Package Maintainer Role::
* Getting Started as a Package Maintainer::
* Updating and Merging with Mercurial::
* Committing and Pushing a Package Change::
* Updating a Package to a New Upstream Version::
* Advice to Package Maintainers::
@end menu



@node The Package Maintainer Role, Getting Started as a Package Maintainer, , XEmacs Package Maintainer
@subsection The Package Maintainer Role

The @dfn{package maintainer} is basically a liaison between two
communities: the XEmacs developers, and the users of the package, who
will typically not be Lisp programmers, and perhaps not programmers at
all.  Because the package maintainer represents the interest of a
community which often is not otherwise active in XEmacs development, he
is the ultimate authority on what goes into the package.  Probably he
will extremely rarely wish to oppose changes made by members of the
Review Board (who have the authority to review and approve changes to
any part of XEmacs).  However, he should feel free to make any changes
he thinks useful for his package; he does not need to ask anyone's
permission, and may approve or veto submissions by other users, and
incorporate them in the package as he sees fit.

The responsibility accepted is simply to pay attention to the package.
The package maintainer should stay on top of progress in the upstream
versions of the libraries in the package, and should subscribe to the
XEmacs Beta and XEmacs Patches mailing lists to watch for bug reports
and patches relevant to it.

We also hope and expect that the package maintainer will take part in
updating and improving the package, but we don't expect him to be a
coding wizard.  It's possible to be a package maintainer even with
very little knowledge of the code.  One can always ask for advice on
XEmacs Beta, or directly of experts on whatever the problem area is.
The roles of the package maintainer and of the core team are
complementary: the package maintainer stays in contact with his
community and finds out what the needs are; the core team provides
advice, information about how XEmacs works, and often patches and
documentation.



@node Getting Started as a Package Maintainer, Updating and Merging with Mercurial, The Package Maintainer Role, XEmacs Package Maintainer
@subsection Getting Started as a Package Maintainer

@cindex bitbucket.org
@cindex Mercurial recipes

The first step is to clone the package from the source repository.

The XEmacs packages are organized using Mercurial subrepositories (aka
subrepos).  This means that each package lives in its own Mercurial
repo, plus there's one more repo at the top level.  Although it's
possible to clone a single package repo, it's better to clone the
entire tree, so that you get the build infrastructure that the top
level provides.  The simplest way to do this is as follows:

@example
hg clone https://bitbucket.org/xemacs/xemacs-packages mypackages
@end example

This will take a while, and about 210MB of space.  It's possible to do
without most of the packages (for example, most modes can delete all of
the mule-packages subtree), but the Lisp programming language makes it
very easy to call functions in one package from another, and
interdependencies are frequent.

The next step is to configure any packages that you want to change so
that they can be pushed back to Bitbucket.  Two approaches have been
shown to work: ssh, and https with your Bitbucket login.

For ssh, you will need to register an ssh public key at Bitbucket.  On
many systems you can generate a key pair using the @command{ssh-keygen}
command.  You will also need to change the @code{default} line in the
@file{.hg/hgrc} for each package to

@example
default=ssh://hg@@bitbucket.org/xemacs/@var{package_name}
@end example

For https, change the @code{default} line in the
@file{.hg/hgrc} for each package to

@example
default=https://@var{login}@@bitbucket.org/xemacs/@var{package_name}
@end example

@noindent
where @var{login} is your Bitbucket login name.

The package developer is welcome to change anything in the repo for
his or her
package.  However, there are a couple of administrative
files that are conceptually the "property" of the package system.  These
are @file{package-info.in} and the @file{Makefile}.  There is almost
surely no need to change either at this time, except to change the
@samp{MAINTAINER} variable in the @file{Makefile} to contain the
maintainer's name and email address.  The package maintainer should
never change the @samp{VERSION} variable; that is automatically
maintained by the package release engineer (currently Norbert Koch) who
does the releases of new versions of packages.  You should keep the
@samp{AUTHOR_VERSION} variable in sync with upstream, if that makes
sense.  It may be possible and convenient to have @code{AUTHOR_VERSION
== VERSION}; ask the package release engineer about it if that seems
attractive.

So now you can

@example
cd mypackages/xemacs-packages/@var{package_name}
xemacs Makefile
# change MAINTAINER to your name and address
# make a patch with hg diff > my.patch and send it to XEmacs Patches
hg commit -m "Update MAINTAINER name and address." Makefile
hg push
@end example

which is a good test that everything is working.  You can find out
more about Mercurial and the XEmacs repository at
@url{http://www.xemacs.org/Develop/hgaccess.html}.  Additional
documentation on Mercurial Subrepositories is at
@url{http://mercurial.selenic.com/wiki/Subrepository}.

Many maintainers who have a separate repository for the upstream project
do not send patches, but simply announce a synch to upstream.  However,
at least at first it is advisable to send patches, so that other
developers can give you advice.

The next step is to copy the @file{packages/Local.rules.template} file
to @file{packages/Local.rules}, and edit it to fit your environment.
The main things are to make sure that the @samp{XEMACS} variable points
to the appropriate XEmacs binary, and that the @samp{STAGING} directory
is set to something useful.  Now you can build a test package by simply
typing @kbd{make bindist}.

When you push a change to the master packages repository, you should
notify the package release engineer,
currently @email{viteno@@xemacs.org,Norbert Koch}, about your
intentions.  Norbert is pretty aggressive about making new packages and
putting them up for download.  If you don't want that after a given
change, you should tell him so.  (This advice may or may not apply to
the next release engineer.)

For internal communication purposes, we make aliases for the maintainer
and the package @samp{@@xemacs.org}. The package maintainer addresses are

@example
@var{firstname.lastname}@@xemacs.org
@end example

You can use these publically as you see fit, or not.  The package
addresses are

@example
@var{package}-bugs@@xemacs.org
@var{package}-discuss@@xemacs.org
@var{package}-patches@@xemacs.org
@var{package}-maintainer@@xemacs.org
@end example

The last alias is set to the maintainer address.  The @samp{bugs-} and
@samp{discuss-} aliases are redirected to XEmacs Beta, and the
@samp{patches-} address to the XEmacs Patch forum.  You can ask that
these be changed at any time, for example if you prefer to get mail
about the XEmacs package in upstream project channels rather than XEmacs
channels.

@node Updating and Merging with Mercurial, Committing and Pushing a Package Change, Getting Started as a Package Maintainer, XEmacs Package Maintainer
@subsection Updating and Merging with Mercurial

@cindex Mercurial recipes

Although the package maintainer is normally the only person to update
a package, it's possible that the repo on Bitbucket will contain
changes that aren't in your local repo.  If this happens, you will
need to merge in those changes before pushing your changes.

As a general recommendation, you should commit your local changes
before pulling from the parent repository.  Having your changes
committed means they will not be lost in case something goes awry
during the merge process.

If you need to run @samp{hg merge}, you should do an @samp{hg commit}
after you have finished merging the changes.  This will make it easier
to distinguish additional work from changes that resulted from the
merge.

Assuming you have the entire package tree, the most reliable way to get an
update is to do @samp{hg pull -u} in the top-level repository.  The 
@samp{-u} (or
a separate @samp{hg update}) is necessary to pull the subrepo updates from
the parent repository.

If a merge is needed in your package subrepo, Mercurial will indicate it
when processing your subrepo
with the string @samp{+1 heads}.  You can then use
the normal @samp{hg merge} and @samp{hg commit} commands within the subrepo.


@node Committing and Pushing a Package Change, Updating a Package to a New Upstream Version, Updating and Merging with Mercurial, XEmacs Package Maintainer
@subsection Committing and Pushing a Package Change

@cindex Mercurial recipes

Normally you will just push changes from your package (sub)repo, not
the top-level packages repo.  You can use @samp{hg stat} to check for
uncommitted changes.  After your final commit, you can use 
@samp{hg outgoing} to list the changeset(s) that you will be pushing.

If your push fails with an error message about creating multiple
heads, that usually means that changes have been made in the parent
repo since the last time you pulled from it.  It's usually best to
pull down those changes and (re)run @samp{hg merge}.  Retest as needed,
review your changes, commit, and try again to push.


@node Updating a Package to a New Upstream Version, Advice to Package Maintainers, Committing and Pushing a Package Change, XEmacs Package Maintainer
@subsection Updating a Package to a New Upstream Version

@cindex Mercurial recipes

If the XEmacs package sources are exactly the same as the upstream
sources, updating to a new upstream version is easy: just copy in the
new sources and update @samp{AUTHOR_VERSION} in the @file{Makefile}.
Build, test, commit, and push.

Often, though, the XEmacs package has diverged from upstream.  In this
situation, the package maintainer can keep a pristine copy of the
most recent upstream version (i.e., the version that the XEmacs
package is based on).  Updating to a new upstream version then
involves the following steps:

@enumerate
@item
Diff the new upstream version against the previous upstream version to
generate a patch file.

@item
If necessary, massage the patch file to reflect the XEmacs file
layout, or to remove diffs for files that are not in the XEmacs
package.

@item
Make sure that your repository has the latest changesets from
Bitbucket.

@item
Apply the patch and resolve any conflicts by hand.

@item
Manually register any new files with Mercurial (@samp{hg add}) and remove
any files that have been deleted (@samp{hg rm --after}).

@item
Build your package (and optionally build the entire package tree).
Test as seems appropriate.

@item
When you are ready (e.g., after testing), commit and push the new
version as described in the previous section.  
    
@end enumerate

After pushing, monitor @uref{http://www.contactor.se/~matsl/smoketest/,
the package smoketest} in case your changes break the build of other
packages.

@heading ChangeLog files

Many upstream packages provide their own @file{ChangeLog} files.  You
may wish to rename those to @file{ChangeLog.upstream} (or some
variation), so that they are separate from the XEmacs @file{ChangeLog}
files.  You can refer to the upstream @file{ChangeLog} file in the
@file{ChangeLog} entry that you create when updating to a new upstream
release.  For example:
    
@example
    YYYY-MM-DD  J. Random Hacker  <jrh@@xemacs.org>
    
        * Sync with foobar 2.7.
        Please see the ChangeLog.upstream files for details.
@end example


@node Advice to Package Maintainers, , Updating a Package to a New Upstream Version, XEmacs Package Maintainer
@subsection Advice to Package Maintainers

This section contains some as yet unorganized advice to package
maintainers, especially those who are coming from a community which uses
XEmacs but normally develops in a language other than Lisp.
@emph{I.e.}, the maintainer of an editor mode.

@heading Setting Up to Build Your Package

Building a package almost always requires the presence of the
@emph{source code} for other packages.  Almost all packages depend on
the @file{xemacs-base} package, for example.  Therefore the recommended
procedure is to check out the whole package tree, configure
@file{Local.rules}, and do a full build with @kbd{make} from the top.
(After that you should keep the tree up-to-date,
@xref{Updating and Merging with Mercurial}, and
occasionally do a @kbd{make} to keep things in order.)  Having
done this once, you can thereafter normally simply do @kbd{make} and
@kbd{make bindist} in your package's top directory.

We know this is annoying, but disk space is cheap, and the requirement
for a full build is a one-time thing.  After that, you can just do @kbd{make
bindist} in your package's directory.  Suggestions for improvement of the
process @emph{are} welcome, but they must account for the need to
provide macro definitions and autoloads.

@heading Cloning from your local copy

The clone command in @ref{Getting Started as a Package Maintainer}
produces a packages tree that can be
built, but because of the way the subrepositories are laid out, you
cannot clone it further.  If you wish to create further clones, you
should create one more directory layer, e.g.,

@example
mkdir mypackages
cd mypackages
hg clone https://bitbucket.org/xemacs/xemacs-packages
@end example

and then run the following script.  In the example above, you would
run it from the @file{mypackages/xemacs-packages} directory.
    
@example
#! /bin/sh
top=$(basename $(pwd))
for d in mule-packages xemacs-packages; do
  for f in $d/*; do
    [ -d $f ] && ln -s $top/$f ..
  done
done
mv ../Sun ../sun
mv ../hm--html-menus ../hm-html-menus 
@end example


@heading Lisp macros and autoloads

Lisp provides @dfn{macros}, which involve @dfn{expansion}, which means
evaluating a Lisp expression which constructs a new Lisp expression.
When a macro is invoked by the interpreter, the second expression is
then @dfn{applied} to the actual arguments to give the actual result.

This separation of expansion from application means that expansion can
take place without knowing the actual arguments.  The most important
example is at compile time.  As a design principle, @emph{compiled code
cannot expand macros} (because it's unnecessary and inefficient), so you
must have all definitions of macros used available at compile time.  The
somewhat similar @dfn{defsubst} is like C @samp{inline}; it's advice to
the compiler, but the function can be called in the usual way.  So
although it's not strictly necessary, it's desirable for efficiency that
defsubst definitions be available to the compiler.

Since Lisp is very dynamic, it's possible to for code to call functions
that haven't been defined yet, as long as the call isn't evaluated until
after the function definition is loaded.  The @dfn{autoload} facility
allows definitions to be loaded the first time they are used.

@heading Application to the XEmacs package infrastructure

When a package is built, of course its Lisp libraries are compiled.  To
ensure that necessary definitions are available, the libraries of the
packages named in the @samp{REQUIRES} Make variable are required, and
the autoload definitions are loaded from generated libraries called
@file{auto-autoloads} in each package.

So you should at least do @kbd{make autoloads} from the top of the
package tree.  (It should be possible to do a more minimal set of
auto-autoloads, just the ones that your package and packages it depends
on use, but there's no automatic way to compute that set.)

Since the compile process involves expanding macros, which is executing
package code, it will speed up the build process for your package to do
a full "make" from the top.  The speedup may or may not be measurable,
since make itself and simply starting XEmacs to do the compilation are
pretty time-consuming.

@heading Maintaining Package Metadata

If you change the packages that your package depends on, or if you
change the libraries that your package provides, you will need to edit
one or more files to reflect those changes.

To update the packages that your package depends on, edit the
@samp{REQUIRES} list in the package's
@file{Makefile}.

To update the list of libraries that your package provides, edit the
@samp{provides} clause in the package's @file{package-info.in}.

@heading For the future

Some attempts have been made to track the dependencies on macros and
autoloads, but the problem turns out to be fairly hard because it's
possible to dynamically compute the names of functions to call, and
things like that.  Thus a program to analyze dependencies must
actually understand Lisp semantics.  We've found it most reliable to
just build the packages, and set up dependencies when errors
occur.

@heading XEmacs-Specific Changes

You can make XEmacs-specific changes easier to find by tagging them
with this comment:

@example
;; XEmacs change
@end example

Of course, the more variances there are between the upstream code and
the XEmacs package, the harder it will be to update to new upstream
versions.  So the general recommendation is to work with the upstream
developers to get any such changes incorporated into the upstream code
base.

@heading Changes to Other Packages or Top-Level

Sometimes your changes may require changes to code that you don't own.
For example, API changes in a new release of your package may break
other packages.  Also, the top-level repo has some package-specific
data, like whether the sources are in the package's top-level
directory or in a @file{lisp} subdirectory@footnote{See
@samp{package-directory-map} in @file{package-compile.el}.}.
So it's possible you will need
to make changes in the top-level repo as well.

If you need to make changes in code that you don't own, send mail to
XEmacs Beta to ask for assistance.  Describe the changes that you want
to make (and why) and ask for instructions on how to proceed.


@heading Getting Help with Your Package

If you want advice on the code itself, just post it to XEmacs Patches,
which is basically designed to put new code that is believed to be ready
to be committed in front of the reviewers.  Since you're the maintainer,
you should mention explicitly that you want review.  Otherwise people
will assume you know what you're doing, even though you know you
don't.

If you're more interested in whether it's a good idea or people will use
it, then post to XEmacs Beta, where a lot more people will see it.
Alternatively you may want to post to package-specific channels, either
an upstream project or the channels devoted to the language it
manipulates.  To the extent that fixes have been submitted by the
community, this fits into the latter case, and you only need to consult
XEmacs channels if they don't work as expected.

Finally, if it's a little of both, you can cross-post.  This is useful
in cases where you know you want to commit this patch but you want
advice on what needs to be done next.

@heading Learning About Emacs Lisp

In this case posting to XEmacs Beta and/or comp.emacs.xemacs is best,
because there are many competent Lisp hackers who are not core
developers.  In many cases, for example, font lock and indentation, this
is probably not so much "learning Lisp" as "learning how Emacsen do font
lock and indentation".  Still, these are skills that are quite common
outside of the core developer group.

Many of the editor features are (unfortunately) relatively
fork-specific.  Emacs and XEmacs do them somewhat differently,
especially font-lock.  Nevertheless, you may also get some help on
channels like comp.emacs and gnu.emacs.help.  (Not
@samp{emacs-devel@@gnu.org}, please; XEmacs-specific stuff is off-topic
there, and even individual gurus won't be able to help much, since
XEmacs code has diverged substantially.

For Emacs Lisp itself, there's some tutorial material in
@ref{Top,the XEmacs Lisp Reference manual, , lispref}, and GNU
distributes an Emacs Lisp tutorial.  However, the GNU tutorial is really
more of a generic Lisp tutorial, with a few examples drawn from the
Emacs domain.  The Lisp Reference is pretty well organized; if you have
trouble finding references to what you need to do, or don't understand
what it says, feel free to report it as a bug.  It's not always possible
to improve it, but it's always worth trying!



@node XEmacs Reviewer, Meta-Maintainer, XEmacs Package Maintainer, The Work Roles
@section XEmacs Reviewer

@cindex reviewer
@cindex XEmacs Review Board
@cindex maintainer
@cindex committer
@cindex xemacs-patches mailing list
@cindex mailing list, xemacs-patches
@cindex xemacs-review mailing list
@cindex mailing list, xemacs-review
@cindex maintainer, nonexistence of authoritative
@cindex nonexistence of authoritative maintainer

A @dfn{reviewer} is a developer who may approve or veto patches proposed
for application to the XEmacs core code.  They are expected to subscribe to
@value{PATCHES-LIST}, the channel for submission of patches to the
XEmacs code base and documentation sources.  The collection of reviewers
constitutes the @dfn{XEmacs Review Board}, which is responsible for
arbitrating conflicts among reviewers, for relations to other projects,
for changes to the development
process described in this @emph{Guide}, and for giving access to
@value{PROJECT} resources to developers, including selecting new
reviewers.
@c #### @xref{XEmacs Review Board}.
Unlike many projects, the
@value{PROJECT} does not have a single authoritative @dfn{maintainer}.
Policy discussions are conducted on the @value{REVIEW-LIST}.  Only
reviewers are subscribed, but any developer may post.

Reviewers are recruited (or are volunteers) from the ranks of the
committers.  The primary qualification for reviewer is a track record of
submitting code and other contributions, constructive criticism of
others' patches, and general discussion on the xemacs-patches,
xemacs-beta, and xemacs-design mailing lists.  In other words, if you
act like a reviewer, you're likely to be asked to be one.

@menu
* Appointing New Reviewers::    
* Welcoming New Reviewers::     
@end menu



@node Appointing New Reviewers, Welcoming New Reviewers, XEmacs Reviewer, XEmacs Reviewer
@subsection Appointing New Reviewers

@c #### This node needs improvement!!

@cindex @value{BOARD}
@cindex appointing reviewers
@cindex reviewers, appointing

The @value{BOARD} is a self-maintaining cabal.  New reviewers are
appointed when the Board feels having a person as a colleague would
improve the project.



@node Welcoming New Reviewers,  , Appointing New Reviewers, XEmacs Reviewer
@subsection Welcoming New Reviewers

@cindex reviewers, welcoming
@cindex welcoming reviewers

@c #### The information in this message should be parsed out into Work Flow.
When a new reviewer is appointed, a representative of the @value{BOARD}
(typically the meta-maintainer or the mentor of the new reviewer) sends
a welcome message to the new reviewer.  Here's a sample.

@display
To: Newbert Reviewer <newbie@@xemacs.org>
CC: XEmacs Review Board <xemacs-review@@xemacs.org>
Subject: Welcome to the Review Board

Dear Newbie,

Welcome to the XEmacs Review Board.

Your main responsibility as a reviewer is to subscribe to the
xemacs-patches mailing list, and review patches you feel you have
expertise on.  This would include the Snufflopagus OS support and the
Round-the-World-Tour package, of course.  Any additional reviewing you
can do would be very welcome.  If you need to take time off, you can do
so freely.  If it is going to be a substantial block of time, it would
be helpful if you would advise the review board so that other reviewers
can pick up on patches to areas that you would normally review.

Our formal Reviewer's Guide, part of the the Developer's Guide, is still
in draft form.  However, the following guidelines should be pretty close
to current best practice.

Any reviewer may approve and commit patches to the development
"branch" (actually, the Mercurial branch @file{xemacs}).
This includes one's own patches.
If you are submitting a patch that you expect to be controversial or
that you expect other reviewers to take a strong interest in
discussing, you should simply submit it, and note in the abstract that
you intend to commit within a certain time frame.  Eg, other reviewers
will often give you this courtesy with respect to patches to
Snufflopagus-related code.  However, most reviewer patches will be
committed at the time of submission.

If you are approving a submission by a developer with commit
privileges, who actually commits the patch is decided by mutual
convenience of the submitter and the reviewer.  Otherwise the reviewer
must commit the patch.

Approvals and commits are indicated by replying to the patch post,
placing the module (21.5 for the trunk) and the action keywords in all
caps (eg "APPROVE COMMIT 21.5") in the first line of the body, and some
clear abbreviation in the Subject header.  (The repetition is for the
convenience of a patchbot we're planning to install.)  The action
keywords should start in column 1 and be the only text in the first
line.

If you believe a given patch should not be applied in anything like
the submitted form, you should veto it.  As with approves and commits,
you send a reply to the patch to xemacs-patches, with the action
keyword VETO.  In the reply you must explain carefully why the patch
is being vetoed.  A veto is a very strong expression of disapproval,
and can only be overridden by approvals from at least 3 other
reviewers.

Alternatively, you may delay application of a patch pending discussion
or revision.  The keyword QUERY seems to be the consensus for
discussion.  Some reviewers will use QUERY when asking for a specific
revision, other will use REVISE for that case.  You should send reply
to _both_ xemacs-patches (for the benefit of patch-tracking) and to
xemacs-beta, where discussion will occur.  Please attempt to direct
followups (eg, using Reply-To) to xemacs-beta.  (We are planning a
'bot to handle this but it has not yet been implemented.)

You may decide to submit an alternative patch.  If the original patch
should therefore not be applied, use the keyword SUPERSEDES.  If at
all possible, make explicit reference to the original patch via a
message-id or an URL to the xemacs-patches archive.

Patches for the stable (21.4) and gamma (currently no release is in
process) branches must be approved by the maintainers (Vin for 21.4)
before being committed.  It is common practice when submitting or
approving a patch for 21.5 to add the keyword RECOMMEND 21.4 to indicate
the patch should also be applied to the stable branch.  If the patch
doesn't apply, you or the original submitter will be asked to work up a
new one that does.

In general, patches for Lisp packages may be recommended by any
reviewer, but the current XEmacs Package Release Engineer prefers to do
most commits himself.  Also, many Lisp packages have external
maintainers, in which case the external maintainer will be responsible
for committing.  (IIRC you are the external maintainer for
Round-the-World-Tour.)

Patches for Web site content may be approved and committed by any
reviewer, but the webmaster, currently Adrian Aichner is most active.
However, he encourages the rest of us to participate.  Note that Adrian
has created a validation target in the Web site make file; be sure to
use it, and any other validation or link-setting tools you have that are
available.  Adrian coordinates changes to the website infrastructure.

The Review Board is also the policy-making body for XEmacs.  Discussion
of policy and personnel matters takes place on the XEmacs Review mailing
list, xemacs-review@@xemacs.org.  This list is closed subscription; you
have already been subscribed.  This list is archived at
http://list-archive.xemacs.org/xemacs-review/.  The archives are
password-protected.  The user is "ObRefFoo", the password is "Fooboref."
Discussion of code and architecture on xemacs-review is strictly
forbidden.  Such discussion should be moved to xemacs-beta or
xemacs-design as soon as you notice it.  As a consequence, xemacs-review
is a fairly low-traffic list.  Policy issues come up on an ad-hoc basis.

On policy matters we generally have operated on the basis of
consensus.  We don't currently have a conflict resolution mechanism,
but there seems to be a growing amount of support for the Apache
model, see http://dev.apache.org/guidelines/.  Participation in policy
discussions is up to the individual reviewer.  Some people do as a
matter of habit, some don't, and some pick their issues.

Feel free to recruit new developers or package maintainers.  In
principle authorization to commit is granted by the review board, but in
practice we have had no dissents.  So in most cases, where the new
developer has been an active participant on one or more of the
development lists, or has specific expertise of value to XEmacs, you
would simply recommend the new developer on xemacs-review.  In the
usual case of no opposition ("lazy consensus"), the next step is to
get an account on Bitbucket, and ask one of the Mercurial
administrators (currently Mike Sperber and Stephen Turnbull) to grant
access to the new recruit.

Your aliases at xemacs.org have already been set up for some time.
For your information, they are

newbert.reviewer@@xemacs.org          newbie@@general-conglobulation.com
newbie@@xemacs.org                    newbert.reviewer@@xemacs.org
newb.reviewer@@xemacs.org             newbert.reviewer@@xemacs.org

These are basically for your convenience; you can post from those
addresses or whatever is convenient for you.  In general we try to use
our @@xemacs.org addresses for "official" announcements that go to
xemacs-announce.  Otherwise, it's a matter of personal taste.

At present you are not pre-authorized to make announcements.  If you
need to make recurring announcements via xemacs-announce, contact the
mailing list administrator at xemacs-mailmaint@@xemacs.org.

You already have commit privileges in the XEmacs repository at
bitbucket.org.  If you have any trouble due to extensions of your
permissions, let one of the Mercurial Administrators (Mike Sperber or
Stephen Turnbull) know.  The directions at

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

seem to be pretty clear.

XEmacs uses facilities at Tux.org (mailing lists, FTP archive, and web
site), in addition to the source code management provided by
Bitbucket.  There is also a web site mirror at SourceForge, but this
is rarely of interest to anyone except the webmaster.  If you need
access to Tux.org, let me know.  The administrators are
very helpful within the constraints of their security policies, and if
there is a reasonable need, they generally respond by providing
access.

If you have any questions, feel free to ask any of the reviewers
directly (see http://www.xemacs.org/Develop/jobs.html) or post to
xemacs-review, as seems appropriate.

Stephen Turnbull <stephen@@xemacs.org>
XEmacs Project Meta-Maintainer
@end display



@node Meta-Maintainer, Release Engineer, XEmacs Reviewer, The Work Roles
@section Meta-Maintainer

@cindex meta-maintainer

The @dfn{meta-maintainer} is a reviewer who
is responsible for general administration, including recruiting
personnel to handle various chores required to keep the project running
smoothly and handling correspondence for the XEmacs Review Board.  The
meta-maintainer generally also fills the role of ``Mr. XEmacs,'' the
public representative of the project.  For this reason the
meta-maintainer should be an individual who has earned the respect and
some power in the community, but the role does not provide any
exceptional power itself.



@node Release Engineer, Jobs List, Meta-Maintainer, The Work Roles
@section Release Engineer

@cindex release engineer
@cindex release manager

A @dfn{release engineer} (also called @dfn{release manager}) is
responsible for the administrative aspects of releasing a distribution,
including such things as ensuring that generated files are committed to
the repository, tagging the version in the repository,
updating release documentation, creating and uploading
tarballs, and making announcements.  Release engineers are @emph{ex
oficio} members of the XEmacs Review Board.  That is, if you are willing
to accept the responsibility of release engineering, and the Board is
willing to accept you, you will be appointed as Reviewer if you aren't
already.

@c #### MAKE A SEPARATE NODE CORRESPONDING TO jobs.html, AND FIGURE OUT
@c HOW TO AUTOMAGICALLY UPDATE AND PUBLISH IT AS jobs.html.
There are currently three XEmacs release engineers: Vin Shelton, for the
stable XEmacs 21.4 branch; Norbert Koch, for the XEmacs package
distribution, and Stephen Turnbull, for the development 21.5 branch
(the Mercurial @file{xemacs} branch).



@node Jobs List,  , Release Engineer, The Work Roles
@section Jobs List

There are a number of auxiliary roles requiring special access to
@value{PROJECT} resources, such as postmaster and webmaster.  However,
these roles do not differ substantially from similar roles in other
projects or organizations, or explicitly control the daily workflow of
the @value{PROJECT}, so definition will be postponed to the sections
describing the roles in detail.  Many of these roles are listed in the
@uref{http://www.xemacs.org/Develop/jobs.html,Jobs List}.



@node The Work Flow, XEmacs Resources on the Internet, The Work Roles, Top
@chapter The Work Flow

This section is a description of current best practices, rather than an
attempt to define a standard.

@cindex patch life cycle
@cindex life cycle, patch
@cindex workflow

@heading The Life Cycle of a Patch

@table @emph
@item Get the sources.
@value{PROJECT}  tarballs are always distributed as source (except in
the case of the Windows installer), but version control simplifies management of
your improvements.  (Third-party vendors such as *nix distributions and
Cygwin may distribute binary packages, but XEmacs no longer does.)

@item Write low-profile code.
Don't distract your users or colleagues from their work.  Just make it
easier.

@item Test your changes.
It's not done until you've proved it works the way you said it would.
As much as possible, tests should be automated, using @file{test-harness.el}.

@item Add a ChangeLog entry.
Tell us what you did.

@item Create the patch.
Dot the i's, cross the t's.  Make sure that it's easy to add to the code
base.  The best way is by using @code{hg diff} against the tip of
the branch or trunk you intend to have the patch applied to.  The
exception is ChangeLog patches, which may be generated using @code{hg
diff -U 0 ChangeLog}, or submitted as plain text.

@item Submit the patch.
Compose the message, especially the Subject: header, so it's easy to
find, easy to identify, easy to review, and easy to apply.

@item Review the patch.
The primary function of the @value{BOARD} is to help you improve your
contributions.  We aim for coherence and power in the interfaces, and
maintainability in the implementation.

@item Assign copyright.
If you like you may assign your coppyright, typically to the FSF; but
this is not required.

@item Commit the patch.
Who commits, how to commit, and when to commit are determined by
negotiation between the developer of the patch and the approving
reviewer.

@item Dispute Resolution
Any three developers will give you four ``best ways'' to do it.  Now you
have to pick one.
@end table

@menu
* About Copyright Assignment::  
* Scratching That Itch::        
* Get the Sources::             
* Write Low-Profile Code::      
* Test Your Changes::           
* Add a ChangeLog Entry::       
* Create the Patch::            
* Submit the Patch::            
* Patch Review::                
* Committing the Patch::        
* Dispute Resolution::          
@end menu



@node About Copyright Assignment, Scratching That Itch, The Work Flow, The Work Flow
@section About Copyright Assignment

@cindex assignment of copyright
@cindex copyright, assignment of

Although XEmacs is a derivative of GNU Emacs, XEmacs is not a GNU
project, nor does it require a copyright assignment to the FSF or anyone
else.  However, according to the FSF's legal advice, the best way to
protect your investment in free software is to assign your copyright to
the FSF (or other free software trust), which is required by its
covenants of incorporation to actively defend free software it holds.
You may also wish to respect the wishes of Richard Stallman, the first
author and current maintainer of Emacs.
Finally, you may wish to support the FSF's advocacy of free software by
assigning your copyright to the FSF.  At the present time, the
@value{PROJECT} neither advocates nor discourages this action; it's up
to you.

Also, be aware that in January 2005
Richard Stallman explicitly denied that such assignments would
facilitate adoption of XEmacs code by GNU Emacs; if you want your code
to be used in GNU Emacs, you will have to resubmit it directly to the
GNU Emacs project.  (The assignment is acceptable for use in Emacs, but
Emacs developers are not allowed to port others' code from XEmacs to GNU
Emacs, even if it's assigned; the original developer must participate in
the process.)

Get more information about procedures from the
@email{emacs-devel@@gnu.org,GNU Emacs developers' mailing list} or from
@email{rms@@gnu.org,Richard Stallman}.  You may also wish to review
@uref{http://www.gnu.org/prep/maintain.html,Information For Maintainers
of GNU Software}, although it is not directly related to @value{PROJECT}
procedures.



@node Scratching That Itch, Get the Sources, About Copyright Assignment, The Work Flow
@section Scratching That Itch

@c #### needs revision

As always in free software, a patch starts life when some developer
somewhere gets an itch.  It might be an irritating bug, or someone's
report of a bug that bites them; a new feature, whether one's own
brilliant inspiration, a user request, or simply the mindless
determination to keep up with the other One True Editor.



@node Get the Sources, Write Low-Profile Code, Scratching That Itch, The Work Flow
@section Get the Sources

Maybe the developer has never worked on XEmacs before.  In that case,
he'll need to check out the source tree from the Mercurial
repository (@pxref{Mercurial Repository}).  True, he may already have the
whole package because he built from source after downloading a tarball.
However, tarballs often lag current development by many months, and
there's nothing that turns a maintainer off like a patch that doesn't
apply because it was generated against an old version.  Furthermore, the
developer needs to keep track of the original file in order to generate
a correct patch, which can be quite difficult if you go through several
iterations working on a complex issue.



@node Write Low-Profile Code, Test Your Changes, Get the Sources, The Work Flow
@section Write Low-Profile Code

@quotation
As for the best leaders, the people do not notice their existence.
... When the best leader's work is done, the people say, ``We did it
ourselves!''
@end quotation

Software engineering is like leadership: true excellence means things
``just work,'' and nobody notices that you've intervened.  Of course,
nobody's perfect, and how you choose which imperfections you will and
won't admit defines your style.  However, we can derive some ideas about
what kinds of submissions are more likely to be generally approved.

With respect to software @emph{users}, we have the @strong{principle of
least astonishment}.  Users will have a more pleasant experience and
work more efficiently if similar gestures in similar contexts produce
analogous results.  This applies to APIs, as well; if
@code{forward-char} takes an optional signed integer argument and there
is no @code{backward-char}, other developers will likely be rather
annoyed if you define separate @code{forward-word} and
@code{backward-word} functions, each taking a required non-negative
integer.

Of course interface design is a matter of judgment, but in cooperating
with other developers there's a more technical standard that should also
be applied: @strong{minimize your patches}.  This principle extends to
the degree of violating coding standards in situations like the
following example.

@example
@{    /* new compound statement to enclose new_local_variable */
  int new_local_variable = initializer ();
@{    /* @strong{don't} reindent this brace      */
     /* or the following 25 lines, omitted here */
  new_local_variable = iterator (new_local_variable);
     /* or the following 10 lines, also omitted */
@}    /* nor the closing brace                   */
@}
@end example

This makes it easier to identify what has been changed, and equally
important, what has not, when reading the patch.  It also makes it more
likely that two semantically independent patches will not interfere with
each other.  For similar reasons, @strong{follow the established coding
standards} and resist the temptation to ``beautify'' code that is not
directly relevant to your changes.

If you follow these practices habitually, your patches will be more
rapidly accepted with fewer requests for revision, and you will have
more credibility when you do need to make an exception to the rule.



@node Test Your Changes, Add a ChangeLog Entry, Write Low-Profile Code, The Work Flow
@section Test Your Changes

XEmacs provides a suite of regression tests which you can run with
@code{make check}.  Run them often, and definitely before you check in.
Fixing one bug is hardly progress if it introduces another.  Whenever
you fix a bug, try to add a test for it to the test suite so it will be
detected if it reappears, or if you fix fails on another platform.

Whenever you add a feature, add new tests to validate its functionality.

Some packages provide their own tests, which you should run before
submitting changes to those packages.



@node Add a ChangeLog Entry, Create the Patch, Test Your Changes, The Work Flow
@section Add a ChangeLog Entry

@strong{Needs review!!}

Add a log entry to @file{ChangeLog} file in the ancestor directory
closest to each changed file.

@menu
* ChangeLogs::                  
* Log Messages::                
@end menu

@node ChangeLogs, Log Messages, Add a ChangeLog Entry, Add a ChangeLog Entry
@subsection ChangeLogs

@strong{This section is pretty close to correct for XEmacs.  Needs review.}

@cindex ChangeLog

Each module should have its own @file{ChangeLog}.  Change logs are cool
because they summarize all the changes in one place, and provide
visibility to the changes to those who do not have access to the source
repository.

Here is an example @file{ChangeLog} entry:

@example
2001-02-18  Bill Wohler  <wohler@@newt.com>

        * Release mh-e-doc-1.3 for Emacs 21.1.

        * doc/mh-e.texi (Viewing): Added mh-header-display index entry.
        (Organizing,Customizing Reading): Added mh-kill-folder index entry.

        * doc/fixhtml (dohtml): Now part of main program now that program
        only fixes HTML files.  Added -w and strict usage.
        (usage,dodvi,doinfo): Deleted.
        (fix_ref_links): Fixed a few uninitialized variables.  Found a
        couple of variables and commands that weren't indexed.

        * doc/Makefile (EMACS): Point to $(TOP)/../remote/emacs.
        (XEmacs-DOCS): Added all relevant files.
        (ONLINE_DIR): Contains target directory for online files.
        (TEXI2HTMLFLAGS, MAKEINFOFLAGS): Added.
        (dist): Tags will have doc in them, so don't need to add.  Release
        will now have all relevant files, rather than just mh-e.texi.
        (install-emacs): First ask user if he has updated and incorporated
        target emacs directory.
        (install-online): Implemented.
        (%.info,%.html,%.dvi,%.ps): Added.

        *doc/mh-e.texi (Viewing, Showing): Use new keymaps (closes
        SF #621632).
@end example

The first bullet shows the text that should be used when releasing a
module.

As usual, the string in parenthesis indicates the documentation
section, Makefile variable or target, or program function or variable.
If you do not use the Emacs @file{ChangeLog} commands such as @kbd{C-x
4 a} (@code{add-change-log-entry-other-window}) which inserts this
text for you (even from a diff!), please do follow its conventions.

Note that the date, the full name, and the email address are separated
by pairs of ASCII spaces, the date is in YYYY-MM-DD format, and the
email address enclosed in angle brackets.  The leading space in the log
entries is encoded as an ASCII TAB, not as 8 spaces.  These formatting
rules are mandatory, because ChangeLog modes depend on these heuristics.

Multiple targets with the same text may appear in the same entry.

@cindex Debian
@c #### @cindex SourceForge
@cindex XEmacs tracker

If your patch is related to a reported issue, please note the issue in
the ChangeLog.  For consistency, phrase the issue number as follows
(@pxref{Updating NEWS}).  For the XEmacs tracker, use

@example
    (closes issue1234).
@end example

You may also be aware of third party reports, such as in the SourceForge
or Debian trackers.  In those cases include the name of the project
maintaining the tracker, and maybe an URL:

@example
    (closes SourceForge #621632).
    (closes Debian #234234).
@end example

The XEmacs manual has full documentation on the @file{ChangeLog}
commands.

When you check in the change log, you do not need to supply any log
message.

@node Log Messages,  , ChangeLogs, Add a ChangeLog Entry
@subsection Log Messages

@strong{This section, written by Bill Wohler for MH-E and lightly edited
to substitute ``XEmacs'' for ``MH-E'', is pretty close to correct for
XEmacs, at least in the case of implicit self-approval.  Needs review.}

@cindex log messages
@cindex ChangeLog

Log messages for Mercurial checkins
should be taken from @file{ChangeLog}.  Given the
@file{ChangeLog} in the previous section, here is what the log for
@file{fixhtml} might look like:

@example
    (dohtml): Now part of main program now that program
    only fixes HTML files.  Added -w and strict usage.
    (usage,dodvi,doinfo): Deleted.
    (fix_ref_links): Fixed a few uninitialized variables.  Found a
    couple of variables and commands that weren't indexed.
@end example

Note that the @code{*} and the filename have been removed, but this is
not mandatory.  However, if the same log message is used for multiple
files, then the associated @code{*} and filenames will need to be
present to separate the messages.

It is not necessary to add release information since that
information will be encoded in the tags.

At worst, setting the log information will be a cut and paste
operation.  At best, it will be a keystroke or two.  Currently cut and
paste is required because the XEmacs version of VC does not support
Mercurial.

I specify the following for @code{log-edit-hook} to make life easier:

@example
    (defun my-log-edit-hook ()
      "This assumes that you have already written a ChangeLog entry."
      (setq paragraph-start (concat paragraph-start "\\|(.*):"))
      (fill-region (point-min) (point-max)))
@end example

Log messages for files named @file{ChangeLog} may be empty.



@node Create the Patch, Submit the Patch, Add a ChangeLog Entry, The Work Flow
@section Create the Patch

@cindex Mercurial recipes

(The following lines describe the current patch creation standard for
developers without commit access, committers, and reviewers alike.  An
optional alternative procedure for @emph{reviewers only} was
adopted in first quarter 2005.)

Patches should be created using a standard diff(1) such as provided by
GNU diffutils, or implemented by Mercurial.  A patch should be a
@dfn{changeset}, that is, it should collect all of the related changes
required to implement the improvement in a single file or message.  The
patch must be a context diff to avoid spurious commits.  The @samp{diff
-urN} format produced by GNU diff is strongly
preferred (except for @file{ChangeLog}; see below).  @strong{N.B.} If
you use older diffs, please check for the
presence of full relative paths in three places: the @samp{Index},
@samp{---}, and @samp{+++} lines.  If the latter do not have the
appropriate relative paths, patch(1) will invariably @emph{fail} to find
the target file, and the application will fail.

Any @file{ChangeLog} diffs must be removed from the main diff.  Because
@file{ChangeLog} is changed in the same place (the beginning) with
@emph{every} patch, context conflicts are extremely likely.  On the
contrary, since @file{ChangeLog} entries are essentially independent of
each other, a @emph{contextless} @samp{diff -U 0} format patch at line
0, or plain text that can be easily cut and pasted, is the preferred
format for the @file{ChangeLog} diff.  These should be prepended to the
changeset.


@node Submit the Patch, Patch Review, Create the Patch, The Work Flow
@section Submit the Patch

@cindex patch submission
@cindex submission, patch

(The following lines describe the current patch submission procedure for
developers without commit access, committers, and reviewers alike.  An
optional alternative procedure for @emph{reviewers only} was
adopted in first quarter 2005.)

Send the patch by email to @value{PATCHES-LIST}.  The subject line
should indicate the branch or package in square brackets at the
beginning of the field.  Some developers like to include the keyword
@samp{PATCH}; it is optional.  After the square brackets, some mnemonic
reference to the nature of the patch should be given.  This might
include the file that is patched or the bug issue being addressed:

@example
Subject: [21.5] src/regex.c: synch to recent GNU Emacs

Subject: [PATCH web] Announce the release of XEmacs 21.4.6

Subject: [21.4 21.5] Fix mail truncation bug
@end example

The first line of the message may contain special keywords.  The only
ones normally used by non-reviewers are @samp{SUPERSEDES} and the module
names.  The keyword @samp{SUPERSEDES} @strong{must be used} if the patch
is intended to be applied @emph{instead} of another addressing the same
issue.  In this case the message @strong{should} be constructed as a
reply to the patch it supersedes (or to some followup to that patch).
That is, the message header should contain a properly constructed
@samp{References} header or an @samp{In-Reply-To} header or both.
Optionally, if it is difficult to do this for some reason, an URL
pointing to the thread in @value{PATCHES-LIST}'s archives, or (less
desirable) the superseded patch's message ID, @strong{must} be included
in the message body.

It is best practice to include the module name(s) if any keywords are
used.  The module name(s) @strong{must} be present in the case of an
original patch that applied to more than one module.  For example, it is
fairly likely that if the patch for mail truncation was generated
against 21.4 it will fail to apply to 21.5.  In that case, a new patch
should be generated and the header and top of body of the submission
message should resemble the following example:

@example
From: Newbert Developer <newbie@@users.sourceforge.net>
To: xemacs-patches@@xemacs.org
Subject: [S21.5] Fix mail truncation bug
References: <disappointed.21.5.maintainer@@xemacs.org>
    <original.patch.submission@@users.sourceforge.net>

SUPERSEDES 21.5

Not needed for 21.4.
This patch adapts the fix from
<original.patch.submission@@users.sourceforge.net> to 21.5.

src/ChangeLog:
[etc, etc]
@end example

@menu
* Optional Alternate Procedure for Reviewers::  
@end menu



@node Optional Alternate Procedure for Reviewers,  , Submit the Patch, Submit the Patch
@subsection Optional Alternate Procedure for Reviewers

Patches that are self-approved by a reviewer, and are either expected to
be non-controversial or are part of a project that has the general
approval of the @value{BOARD}, may optionally omit the email submission.
Instead, the responsible reviewer simply commits the patch, and the
repository
commit-trigger will automatically generate and post the patch to
@value{PATCHES-LIST}.  This may be referred to as @dfn{implicit
self-approval}.

@strong{The commit-trigger has
not yet been implemented at the time of writing.  For this reason
implicit self-approvals should still be avoided.  (2007-05-13)}



@node Patch Review, Committing the Patch, Submit the Patch, The Work Flow
@section Patch Review

@cindex patch approval
@cindex approval, patch

(The following lines describe the current patch submission procedure for
developers without commit access and committers.  Reviewers may
optionally use ``commit-and-review,'' described later.  Another optional
alternative procedure for @emph{reviewers only} was adopted
in first quarter 2005.  Called ``implicit self-approval,'' it was
described in the previous section.)

After the patch has been distributed via @value{PATCHES-LIST} reviewers
and other developers should review and test the patch.  Discussion
should continue on the same list.  When a reviewer is satisfied that he
understands the patch, he should post a @dfn{reviewer action}, which is
a reply to the thread stating his formal decision.  The currently
defined reviewer actions are

@table @samp
@item APPROVE
The patch is accepted, and will be committed by arrangement between the
approving reviewer and the submitting developer.

@item RECOMMEND
The patch should be accepted, but it needs to be applied to code the
reviewer doesn't have authority over (either a stable branch or a
package with a designated maintainer).

@item QUERY
The reviewer likes the idea of the patch, but is delaying application
subject to clear-cut revisions, or perhaps mere clarification of the
intent or mechanism of the patch.

@item REVISE
The reviewer is demanding certain revisions, or the patch will be
vetoed.  May be obsolete; current practice strongly favors use of
@strong{QUERY} both for required revisions and for further discussion,
and there seems to be little need to distinguish these cases.

@item VETO
The reviewer thinks the patch is ill-conceived, and requires redesign
before it will be acceptable.
@end table

There has been controversy on the @value{BOARD} about the
meaning of a veto.  Some reviewers interpret it as unalterable
opposition that can only be settled with sabers or pistols, while others
see it as a moratorium that might be, or might not be, permanent.

In cases of the first three actions, the future path of the patch is
clear.  In the case of a @samp{VETO}, the veto may be overridden by
three votes for @samp{APPROVE} among the reviewers.  (It's not clear
to me whether an override requires a majority, including at least three
approvals, or a supermajority of two more approvals than vetos.)



@menu
* Commit-and-Review::           
@end menu

@node Commit-and-Review,  , Patch Review, Patch Review
@subsection Commit-and-Review

A reviewer may self-approve his own submission.  In this case, the
reviewer may use @dfn{commit-and-review}, that is, submit, approve, and
announce the commit in a single post to @value{PATCHES-LIST}.

In cases of implicit self-approval or commit-and-review, other reviewers
are expected to review in a timely fashion, and in the case of a
@samp{QUERY} or @samp{VETO} post their action within a week.  In the
case of a @samp{VETO}, the patch must be reverted immediately, pending
an override or withdrawal of the veto.



@node Committing the Patch, Dispute Resolution, Patch Review, The Work Flow
@section Committing the Patch

@cindex patch, committing a
@cindex committing a patch

Once the patch has been approved, it should be pushed to the source
repository as soon
as possible.  The committer should also send a commit message using the
keyword @samp{COMMIT} as a reply to the approval message.

@menu
* Proposed Alternative Procedure::  
@end menu



@node Proposed Alternative Procedure,  , Committing the Patch, Committing the Patch
@subsection Proposed Alternative Procedure

In the case of implicit self-approval, the changeset log message should
describe the rationale for the patch, and list the affected modules and
subdirectories in the tree.  This should be enough to point reviewers to
the relevant ChangeLog diffs, which will automatically be included.
There will be no manual posts at all to @emph{xemacs-patches}, so there
is no way to supply a message ID reference; that requirement is nullified.

@strong{This procedure is not yet in effect, and the commit-trigger has
not yet been implemented at the time of writing.  (2009-02-24)}



@node Dispute Resolution,  , Committing the Patch, The Work Flow
@section Dispute Resolution

@cindex contesting vetos
@cindex vetos, contesting
@cindex protesting check-ins
@cindex check-ins, protesting
@cindex dispute resolution

@strong{This is a first hack draft by @samp{stephen}.  I have no idea
whether it represents my own ``true'' opinion, let alone anyone else's.}

There seems to be general agreement that @value{PROJECT} resources
should be used to serve ``the users' needs'' first, before being used
for developers' play---but there is disagreement over who those users
are, and what their needs might be.

There is general agreement that one of the advantages to working on
XEmacs is the overall coherence of most of its architecture, and the
dedication of the team to refactoring broken designs.  However, the
developers with fewer resources to devote feel overwhelmed by the ``code
churn'' generated by the most prolific developers, and protest that
memorizing global renamings and the like are rather frivolous ways to
spend reviewer resources.

These conflicts typically manifest as a dispute over some reviewer's use
of a veto.  Therefore I propose the following guidelines for use of
vetos.

@table @emph
@item Only patches can be reviewed.

And therefore, only patches can be vetoed.  People can propose, purely
for discussion, whatever they like.  Such proposals @strong{may not} be
vetoed.  If somebody wants to submit a patch that's clearly against the
sense of some member of the board, let them.  It will be vetoed.  If
they resubmit a real revision, the reviewers must be allowed to consider
it.

Note how this deals with the ``use the ISO standard @samp{size_t} type
for positive variables'' kind of issue.  There's essentially only one
way to write that patch.  If it is vetoed and an attempt to override
fails, the policy of the @value{BOARD} is clear.  The patch should not
be resubmitted until there's good reason to suppose the average stance
of the board has shifted considerably.

@item Reviewer decisions apply to the whole patch.

Including vetos.  This makes megapatches risky, obviously.  It's up
to the contributor to separate the parts; if something unacceptable is
submitted as part of the megapatch, the reviewer should not be
pressured to accept the whole, nor to do the surgery himself.  If the
megapatch is that important to the project, the board should be willing
to override the veto.  If the contributor can't get that support, he
must split out the acceptable parts.

@item Reasonable time constraints for reviewers.

Except for global substitutions, megapatches are normally the result of
weeks, even months, of secret work; reviewers should be allowed
proportionate amounts of time to review them.  If the work is done
serially via commit-and-review, or on a branch, or (with approval of the
Board) in @samp{#ifdef}s, then the reviewers get just as much time as
the originator does, and they have no excuse for being ``surprised'' by
the megamerge at the end.

Note that the point of a branch here is @emph{not} incremental merging,
it is to make progress on the megapatch public.  So this costs only the
trivial effort of committing your workspace to the branch every week or
two.  (Of course the big merge at the end will still be a lot of work,
but that would be true if all the work was done in a local workspace and
never committed to a branch.)

@item Each resubmission of a patch restarts the clock.

Reviewers need not work faster just because somebody has resubmitted the
patch three times.  If you submit a large patch with 52 major bugs, you
had better be prepared to wait a year as it gets vetoed once a week,
once for each bug.

@item The submitter must revert an immediate commit if vetoed.

If you take advantage of implicit self-approval, you have no arguments
because you've short-circuited the review process.  Had the patch gone
through the full process, it never would have been applied---you're way
ahead of the game as it is.  Revert the patch.

If the veto is abusive, the abusive reviewer should be disciplined---but
showing that will take discussion, and that must happen after reversion.

@item A veto after commit of a fully reviewed patch must be supported.

If a patch goes through the full submit---review---approve---commit
cycle, it may still be vetoed.  However, in this case the burden of
proof should be on the vetoer.  The committer @emph{may} refuse to
revert, and in that case, the vetoer needs two concurring vetos.  This
constitutes a blocking coalition of three---the patch must be reverted
immediately, even if it seems likely that a vote of the board would back
the commit.  The patch can be reapplied after the vote.

Some patches, ie, not submitted by reviewers, need the full
submit---review---approve---commit process in any case. So if reviewers
want some assurance that their patch won't be reverted after commit,
they can take advantage of full review process (which still allows
self-approval).

(It's arguable that ``full review process'' should mean approval by a
reviewer other than the submitter.)
@end table



@node XEmacs Resources on the Internet, Copying, The Work Flow, Top
@chapter XEmacs Resources on the Internet

@strong{Write this node!}  Get mailing list and newsgroup information
from the @uref{http://www.xemacs.org/Lists/, mailing list page},
available as the module @emph{xemacsweb}.

There should also be a node for the Emacs Wiki.

@cindex XEmacs Resources on the Internet

@menu
* Project Website::             
* Mercurial Repository::              
* comp.emacs.xemacs::           
* xemacs-beta::                 
* xemacs-design::               
* xemacs-patches::              
* xemacs-mule::                 
* xemacs-winnt::                
* xemacs-review::               
@end menu



@node Project Website, Mercurial Repository, XEmacs Resources on the Internet, XEmacs Resources on the Internet
@section Project Website

@strong{Needs review.  Adrian?}

@cindex Project Website
@cindex @value{XEMACSORG}, XEmacs Web space

The @uref{http://www.xemacs.org/, XEmacs home page} contains a brief
overview of the XEmacs project.  This Web space also includes other
internal documents, such as this one.

@c #### this probably belongs elsewhere?  this subtree is more user-oriented.
To install your updates into the XEmacs Web space at @value{XEMACSORG},
simply check out the @file{xemacsweb} module, make
your changes, and check it in.  The commit script takes care of
generating the HTML and pushing the changes to the web servers' document
spaces.


@node Mercurial Repository, comp.emacs.xemacs, Project Website, XEmacs Resources on the Internet
@section Mercurial Repository

@cindex Mercurial Repository

@c #### update the specific links for convenience!!
The Mercurial Repository contains several branches of the trunk
(currently version 21.5).  You can view the repository with an ordinary
browser on the HTTP URL.

@table @uref
@item https://bitbucket.org/xemacs/xemacs-beta
The branch from which beta releases are made.  Direct commits are not
allowed.  Only the gatekeepers (pulling approved patches from the
@file{xemacs} branch) and the Beta Release Manager may commit
to this branch.  The @file{xemacs-beta} branch is expected to always be
in a buildable state.  It should lag the @file{xemacs} branch by less
than a week, unless a patch is found to break the build.

@item https://bitbucket.org/xemacs/xemacs
A public-access URL for the bleeding edge.

@item ssh://hg@@bitbucket.org/xemacs/xemacs
The commit access URL for the bleeding edge.  Although you cannot easily
push changesets that would create a new head, committers who use named
branches should take care not to push from branches other than
@file{default}.

@end table


@node comp.emacs.xemacs, xemacs-beta, Mercurial Repository, XEmacs Resources on the Internet
@section The Usenet Newsgroup comp.emacs.xemacs

@strong{Write me!}



@node xemacs-beta, xemacs-design, comp.emacs.xemacs, XEmacs Resources on the Internet
@section The xemacs-beta Mailing List

@strong{Write me!}



@node xemacs-design, xemacs-patches, xemacs-beta, XEmacs Resources on the Internet
@section The xemacs-design Mailing List

This list is currently inactive.  Traffic that used to go to
@value{DESIGN-LIST} should be directed to @value{BETA-LIST} instead.

@strong{Concerning content, write me!}



@node xemacs-patches, xemacs-mule, xemacs-design, XEmacs Resources on the Internet
@section The xemacs-patches Mailing List

@strong{Write me!}



@node xemacs-mule, xemacs-winnt, xemacs-patches, XEmacs Resources on the Internet
@section The xemacs-mule Mailing List

@strong{Write me!}



@node xemacs-winnt, xemacs-review, xemacs-mule, XEmacs Resources on the Internet
@section The xemacs-winnt Mailing List

This list is obsolete, as the NT console is a fully-supported component
of XEmacs since the release of 21.4.  Archives are still available at
@uref{list-archive.xemacs.org,the XEmacs mailing list archives}.



@node xemacs-review, , xemacs-winnt, XEmacs Resources on the Internet
@section The xemacs-review Mailing List

The XEmacs Review mailing list is a closed-subscription list where the
XEmacs Reviewers discuss matters requiring privacy, including the most
controversial policies, and personnel matters.  If you wish to propose
someone for committer, package maintainer, or reviewer (including
yourself!), post to this list.  Be patient; there will be a moderation
delay (to filter spam).



@node Copying, Nodes borrowed from other projects not adapted to XEmacs, XEmacs Resources on the Internet, Top
@appendix GNU GENERAL PUBLIC LICENSE
@center Version 2, June 1991

@display
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display

@appendixsec Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software---to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

@iftex
@appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex
@ifnottex
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end ifnottex

@enumerate 0
@item
This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The ``Program,'' below,
refers to any such program or work, and a ``work based on the Program''
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term ``modification.'')  Each licensee is addressed as ``you.''

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

@item
You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

@item
You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

@enumerate a
@item
You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.

@item
You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.

@item
If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License.  (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
@end enumerate

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

@item
You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

@enumerate a
@item
Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,

@item
Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,

@item
Accompany it with the information you received as to the offer
to distribute corresponding source code.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
@end enumerate

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

@item
You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

@item
You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

@item
Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

@item
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

@item
If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

@item
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and ``any
later version,'' you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

@item
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

@iftex
@heading NO WARRANTY
@end iftex
@ifnottex
@center NO WARRANTY
@end ifnottex

@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
@end enumerate

@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifnottex
@center END OF TERMS AND CONDITIONS
@end ifnottex

@page
@appendixsec How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.

@smallexample
@var{one line to give the program's name and an idea of what it does.}
Copyright (C) 19@var{yy}  @var{name of author}

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
@end smallexample

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

@smallexample
Gnomovision version 69, Copyright (C) 20@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.
@end smallexample

The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than @samp{show w} and
@samp{show c}; they could even be mouse-clicks or menu items---whatever
suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary.  Here is a sample; alter the names:

@smallexample
@group
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.

@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
@end group
@end smallexample

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.


@node Nodes borrowed from other projects not adapted to XEmacs, Index, Copying, Top
@appendix Nodes borrowed from other projects not adapted to XEmacs

@c #########################################################################
@c #### I haven't seriously worked on the included material. -- stephen ####
@c #########################################################################

@menu
* Support Requests::            
* Bugs::                        
* Feature Requests::            
* Patch Queue::                 
* File Releases::               
* News::                        
* Surveys::                     
* Free Software Directories::   
@end menu


@node Support Requests, Bugs, Nodes borrowed from other projects not adapted to XEmacs, Nodes borrowed from other projects not adapted to XEmacs
@chapter Support Requests

@cindex Support Requests

Support requests are made to @value{BETA-LIST}.  Developers should read
the mailing list frequently, and after a period of inactivity, browse
the @uref{http://list-archive.xemacs.org/xemacs-beta/,recent archives}.



@node Bugs, Feature Requests, Support Requests, Nodes borrowed from other projects not adapted to XEmacs
@chapter Bugs

@strong{We don't have a tracker.  We should.  Describe what it should
look like here.}

@cindex Bugs
@cindex priority
@cindex bugs, priority

Bug reports, feature requests, and discussions that are expected to lead
to bug reports or feature requests are created in
@uref{https://sourceforge.net/bugs/?group_id=13357, Bugs}.  Most
bugs should be set to a priority of 5.

@cindex bug-gnu-emacs
@cindex Debian

Developers should follow the @i{bug-gnu-emacs} mailing lists/newsgroup
and move bug reports into Bugs if it has not been done already.
Similarly, XEmacs bugs reported in other systems should be transfered to
@value{XEMACSORG}.  The bug may be cut and pasted into a new bug report, or a
URL to the source of the original bug report may be all that appears
in the bug report.

A brief lifecycle of a bug proceeds something like this.  A bug is
entered.  A developer ensures that the Category, Priority and Group are
correct.  The Group for an Open bug should be set to the version of
software in which the bug was found, or CVS if it was found in the
latest and greatest.

The assignment of bugs in Bugs follows the honor system.  If you see an
open bug that you think you could handle, assign the bug to yourself.
Bugs that remain open should be reviewed by a member of the
@value{BOARD}, who should try to find a developer to work on the bug.

If you fix a bug, set the resolution to Fixed and group to CVS.  Please
also assign the bug to yourself if you have not done so already, so
you get credit in the
@uref{https://sourceforge.net/tracker/reporting/?atid=113357&what=tech&span=&period=lifespan&group_id=13357#b,
reports}.  If a documentation change is not required, set the status to
Closed.  If a documentation change is required, set the category to
Documentation, and assign the bug to the documentation tsar,
leave the status Open, and set the priority to 3 to set it
aside in listings sorted by priority.

See @ref{File Releases} for a motivation of why this process is useful.

The rest of this section describes the categories and groups that have
been set up for the XEmacs project.

@menu
* Category::                    
* Status::                      
* Group::                       
* Resolution::                  
@end menu

@node Category, Status, Bugs, Bugs
@section Category

@cindex category
@cindex bug category

Several categories have been created for the XEmacs project organized by
function.  They include @i{General}, @i{UI}, @i{MIME}, @i{Security},
@i{Documentation}, and @i{Contrib}

@table @b

@item General

@cindex general bug category
@cindex bug categories, general

The @dfn{General} category is used for bugs that do not belong in any of
the other categories.

@item UI

@cindex UI bug category
@cindex bug categories, UI

The @dfn{UI} category is used for bugs in the software that the user sees
such as font-lock, key definitions, menus, and customization.

@item MIME

@cindex MIME bug category
@cindex bug categories, MIME

The @dfn{MIME} category is used for bugs that pertain to MIME.

@item Security

@cindex security bug category
@cindex bug categories, security

The @dfn{Security} category is used for bugs in the security arena.  At
present, XEmacs does not include any security code, so this category might
be used for PGP interaction.

@item Documentation

@cindex documentation bug category
@cindex bug categories, documentation

The @dfn{Documentation} category is used for bugs in the documentation
arena.  In addition, if there are any code changes made as a result of a
bug report or feature request that require changes to the documentation,
the category of that issue should be set to Documentation after the bug
has been fixed or the feature implemented.  Assign the issue to
@i{wohler} for editing and/or writing of the documentation, and set
the priority to 3 to set the issue aside in listings sorted by priority.

@item Contrib

@cindex contrib bug category
@cindex bug categories, contrib

The @dfn{Contrib} category is used for all bugs in the contributed
software.

@end table

@node Status, Group, Category, Bugs
@section Status

@cindex status
@cindex bug status

The bug @dfn{status} is divided into four sections: @i{Open},
@i{Closed}, @i{Deleted} and @i{Pending}.

@table @b

@item Open

@cindex open bug status
@cindex bug status, open

When bugs are initially created, they are marked @dfn{Open}.

@cindex discussing bugs
@cindex bugs, discussing
@cindex features, discussing

The Bugs and Feature Requests sections are also used as a method to
get the ball rolling among developers.  They are used to register what
we feel we should work on.  For example, a developer may have questions
about the way XEmacs handles MIME that we should discuss before we
attempt to fix it: What do other people do? How should we attack this?
That developer opens a bug report in the MIME category and a
discussion ensues.  Once the disposition of the issue is resolved, the
bug is assigned to a developer.  Later, when the bug is fixed, the bug
can be closed.

Discussion about entirely new features should be opened in the Feature
Requests section (@pxref{Feature Requests}) but otherwise handled in
the same way.

@item Closed

@cindex closed bug status
@cindex bug status, closed

When all aspects of a bug have been fixed, including code and
documentation, the bug is marked @dfn{Closed}.

When setting the status to Closed, the group should be set to Fixed,
Works For Me, Invalid, or Rejected.

@item Pending

@cindex pending bug status
@cindex bug status, pending

You can set the status to @dfn{Pending} if you are waiting for a
response from the tracker item author.  When the author responds, the
status is automatically reset to that of Open.  Otherwise, if the
author doesn't respond within 14 days, then the item is given a status
of Deleted.

@item Deleted

@cindex deleted bug status
@cindex bug status, deleted

If an items has been marked Pending, it will be marked @dfn{Deleted}
if the author of the item does not respond within 14 days.

@end table

@node Group, Resolution, Status, Bugs
@section Group

@cindex group
@cindex bug group

The bug @dfn{group} contains several items.  They include:

@table @b

@item None

Bugs are initially filed in this group.

@item CVS*

Bugs in groups starting with CVS have either been found in the CVS
version (in contrast to a released version) if the Status is Open, or
they have been fixed and checked in if the Resolution is Fixed.

After fixing a bug in a beta release, however, developers should not
set the group to CVS but leave it in the group named for the beta
release.  Just be sure to mention the issue number in the ChangeLog so
that it can be noted in the next release announcement.

@item XE*

Bugs in groups starting with XE have either been found in the given
version if the Status is Open, or fixed in the given version if the
Status is Closed.

@end table

@node Resolution,  , Group, Bugs
@section Resolution

A bug can appear in various states:

@table @b

@item Accepted

@cindex accepted resolution
@cindex resolution, accepted

The @dfn{Accepted} resolution means that QA has accepted the fix.
Since we don't have a QA department, it is unlikely that this will be
used in that fashion.  Instead, it can be used to indicate that a
developer feels that a feature request (that someone else posted) has
merit.

@item Duplicate

@cindex duplicate resolution
@cindex resolution, duplicate

The @dfn{Duplicate} resolution means that this bug is a duplicate of
another.  The status may be set to Closed.  Be sure to add a note which
mentions the bug number that this bug is a duplicate of.  If this bug
has some good information in it, the URL to this bug should be added
to the duplicate.

@item Fixed

@cindex fixed resolution
@cindex resolution, fixed

The @dfn{Fixed} group is used to indicate a bug or feature request that
has been fixed.

@item Invalid

@cindex not a bug resolution
@cindex invalid resolution
@cindex resolution, not a bug
@cindex resolution, invalid

The @dfn{Invalid} resolution is used to indicate the problem is with
the user.  In other words, this is not a bug.  See Works For Me.

@item Later

@cindex later resolution
@cindex resolution, later

The @dfn{Later} resolution is similar to the Postponed group, although
it connotates a longer delay.

@item Out of Date

@cindex out of date resolution
@cindex resolution, out of date

The @dfn{Out of Date} resolution is similar to the term OBE (Overcome
By Events).  In other words, the bug has not been fixed, but the code
has changed in ways that make it unnecessary to do so.

@item Postponed

@cindex postponed resolution
@cindex resolution, postponed

The @dfn{Postponed} resolution is similar to the Later group, although
it connotates a lesser delay.

@item Rejected

@cindex rejected resolution
@cindex resolution, rejected

The @dfn{Rejected} resolution means that QA has rejected the fix.
Since we don't have a QA department, it is unlikely that this will be
used in that fashion.  Instead, it can be used to indicate that a
developer feels that a feature request does not have merit.

@item Remind

@cindex remind resolution
@cindex resolution, remind

The @dfn{Remind} resolution is similar to the Postponed and Later
groups, although it connotates an even lesser delay.

@item Wont Fix

@cindex wont fix resolution
@cindex resolution, wont fix

The @dfn{Wont Fix} resolution means that the XEmacs developers
acknowledge that the bug exists but are not going to fix it.  Or the
developers will not implement a feature request.  There is probably a
good reason for these things.

@item Works For Me

@cindex irreproducible resolution
@cindex resolution, irreproducible
@cindex works for me resolution
@cindex resolution, works for me

The @dfn{Works For Me} group is used to indicate a bug that cannot be
reproduced (irreproducible) and therefore cannot be fixed.  See
Invalid.

@end table

@node Feature Requests, Patch Queue, Bugs, Nodes borrowed from other projects not adapted to XEmacs
@chapter Feature Requests

@cindex Feature Requests

Developers should check the
Feature Requests
occasionally for new feature requests and comment on the feature's
usefulness and integrity.  Unless a positive comment has
@c #### define "reasonable"
been added within a ``reasonable'' amount of time, a member of the
@value{BOARD}
may set the status to Closed and the group to Wont Fix.  @value{BOARD}
members should regularly check the list of requested features and prune
the oldest in this way to keep the list to a reasonable size.
@c mh-e-devguide sez:
@c will set the status to Closed and the group to Wont Fix.  If the
@c feature request is not closed, anyone may assign the request to
@c themselves and implement the feature.

After incorporating the feature, update the feature request as
described in the previous section (@pxref{Bugs}).

@node Patch Queue, File Releases, Feature Requests, Nodes borrowed from other projects not adapted to XEmacs
@chapter Patch Queue

@cindex Patch Queue

Developers should check @value{PATCHES-LIST}
occasionally for new patches and comment on the patch's usefulness and
integrity.  This will greatly help reviewers to review patches.  Note
that developers who are active in commenting on patches and bug reports
are the main candidates when recruiting new reviewers.

@c Legally speaking, patches that are less than 15 lines can usually be
@c incorporated, although it is always best to try to incorporate them in
@c a ``clean room'' environment.  Do read
@c @uref{http://www.gnu.org/prep/maintain_6.html#SEC6, Legally
@c Significant Changes} for the details.



@node File Releases, News, Patch Queue, Nodes borrowed from other projects not adapted to XEmacs
@chapter File Releases

@strong{This node and all of its children need to be reviewed and
adapted to the XEmacs process.  One topic that @emph{must} be addressed
is regenerating and checking in generated files.}

@cindex File Releases

This section contains information about how the XEmacs project releases
software.  In additional to making tarballs available, the software and
documentation must be incorporated into Emacs and the online
documentation must be updated.

@menu
* Release Schedule::            
* Release Prerequisites::       
* Updating NEWS::               
* Updating README::             
* Updating Version Number::     
* Updating ChangeLogs::         
* Tagging Releases::            
* Creating Tarballs::           
* Creating @value{XEMACSORG} Releases::  
* Updating the Tracker::        
* Announce the Release::        
* Updating the Emacs Repository::  
* Updating the Debian Package::  
* Updating the XEmacs Package::  
* Updating the Online Documentation::  
* Updating the Free Software Directories::  
* After the Release::           
@end menu

@node Release Schedule, Release Prerequisites, File Releases, File Releases
@section Release Schedule

@strong{Totally bogus for XEmacs historical practice, probably totally
unrealistic as future policy.}

Here is a suggested schedule for a release:

@quotation
@multitable @columnfractions .3 .3 .4

@item @strong{Time}
@tab @strong{Milestone}
@tab @strong{Description}

@item T-4 weeks
@tab Soft Freeze
@tab
All P7 and higher features must be committed.
P6 features should be committed.
Any other new features destined for the release must be committed no
later than this time.
However, note that it is advisable not to release new user-visible
features this late in the game.  It is better to add new features at
the beginning of a release cycle to allow for suitable usability
testing.
Testing commences.

@item T-3 weeks
@tab Hard Freeze
@tab
All P7 and higher bug fixes must be committed.
P6 bug fixes should be committed.
Testing continues.

@item T-2 weeks
@tab Beta 1
@tab
Cut beta release.
Upload to @value{XEMACSORG}.

@item T-1 weeks
@tab Beta 2
@tab
Cut beta release.
Upload to @value{XEMACSORG}.

@item T-0 weeks
@tab Release!
@tab
Cut release.
Upload to @value{XEMACSORG}.

@end multitable
@end quotation

Once a release date has been determined, the milestones leading up to
that release should be posted as a news item (@pxref{News}).

With frequent minor releases, omit the beta releases and
pre-announcement.

@node Release Prerequisites, Updating NEWS, Release Schedule, File Releases
@section Release Prerequisites

@cindex Release Prerequisites
@cindex Coding Conventions
@cindex Emacs Lisp Coding Conventions
@cindex Conventions, verification
@cindex Verification, conventions

@c #### is this relevant?
The first thing to do is to check the code for coding convention
compliance as described in section @ref{Philosophy}.

Next, check for Emacs changes to XEmacs as described in section
@ref{Updating the Emacs Repository}.

@node Updating NEWS, Updating README, Release Prerequisites, File Releases
@section Updating NEWS

@cindex NEWS
@cindex news
@cindex src
@cindex Debian

When the @code{src} module is released, the
file @file{NEWS} needs to be updated.  Separate the old news with
the new with a @kbd{C-l} and follow the existing format for
documenting user-visible changes only including New Features, New
Variables, and Bug Fixes.  List @value{XEMACSORG} issues as @code{(closes SF
#123456)}, as well as third-party issues such as @code{(closes SF
#123456, Debian #123456)}.

In order to find what is appropriate for @file{NEWS}, several
things can be done.

@enumerate

@item
Go to @uref{https://sourceforge.net/bugs/?group_id=13357, Bugs} and
search for all bugs whose status is Closed and group is CVS (no
documentation update needed) or status is Open, group is CVS, and
category is Documentation (documentation update needed but not
finished).

@item
Repeat for
@uref{https://sourceforge.net/tracker/?atid=363357&group_id=13357,
Feature Requests}.

@item
@cindex release-utils
Run the @code{release-utils --variable-changes @var{previous-tag}} to
produce a list of new and deleted variables suitable for inclusion in
@file{NEWS}.

@item
Run @kbd{C-h m} in MH Folder and MH Letter modes in both the new and
old versions to show the key binding changes.

@item
Search for @code{[0-9][0-9][0-9][0-9][0-9][0-9]} in the
@file{ChangeLog} to get a list of SF numbers.

@item
Use the ChangeLog.

@end enumerate

The previous steps usually catch most items.  To use a finer sieve, use
the following commands.  These assume that the last version of XEmacs
was 21.4.20.

@example
    cvs log -rr21-4-20
    cvs diff -rr21-4-20
@end example

See section @ref{Updating ChangeLogs} before checking in this file.

@node Updating README, Updating Version Number, Updating NEWS, File Releases
@section Updating README

@cindex README

Ensure that the target Emacs version is correct, as well as the
supported Emacs versions.

Update the version number in various places in the INSTALL section.

See section @ref{Updating ChangeLogs} before checking in this file.

@node Updating Version Number, Updating ChangeLogs, Updating README, File Releases
@section Updating Version Number

@set VERSIONFILE @file{$@{srcdir@}/version.sh}

XEmacs version information is kept in the file
@value{VERSIONFILE}.   This file must be valid when sourced
by a POSIX shell and when included by a portable Makefile.

The first in a series of stable releases is a special case, because it
involves creation of a new stable branch and affects numbering of the
trunk as well.  In the new stable branch, @value{VERSIONFILE} must
assign the empty value to @samp{emacs_is_beta}.  The value ``0'' is
assigned to @samp{emacs_beta_version}.  The next @emph{even} number
(which is ``0'' in the case that @samp{emacs_major_version} is bumped)
is assigned to @samp{emacs_minor_version}, and
@samp{emacs_major_version} is bumped if that was authorized by the
XEmacs Review Board.  The codename @samp{xemacs_codename} is assigned at
the discretion of the stable release engineer.

At the same time, a new release of the trunk, identical except for
version information, is made.  @emph{The version information is the same
as the stable release}, except that @samp{emacs_minor_version} is bumped
to the next @emph{odd} integer, and @samp{xemacs_codename} is assigned
at the discretion of the beta release engineer.

Release engineers usually choose a theme for codenames and make the
proposed series available in a file.  The name @samp{emacs_beta_version}
probably could have been more aptly chosen, but it is a historical relic
of the fact that it was first used in the beta series, then adopted in
the stable branch.  The name is not user-visible; the value of this
variable is called the patch level in stable branch documentation.

@strong{N.B.} Release engineers should avoid disturbing the order of
variables in @value{VERSIONFILE}.  The variables
@samp{emacs_kit_version}, @samp{infodock_major_version},
@samp{infodock_minor_version}, and @samp{infodock_build_version} are
used for version information of various non-@value{PROJECT} releases,
and should be ignored.  Both of these features are unclean, but users'
auxiliary tools (and some tools distributed by the @value{PROJECT},
including @file{build.el} and @file{build-report.el} in some releases)
often depend on the syntax of this file to work correctly.  In beta
releases, there is an optional variable @samp{xemacs_extra_name} which
is a string that is appended to the version string.  It is currently
automatically updated, and used to identify the Mercurial changeset.

Except in cases involving creation of a new stable branch, update of the
version information simply requires bumping @samp{emacs_beta_version}
and assignment of a new @samp{xemacs_codename}.


@node Updating ChangeLogs, Tagging Releases, Updating Version Number, File Releases
@section Updating ChangeLogs

@cindex ChangeLog

Add a ChangeLog entry to @emph{every} ChangeLog in the tree, marking the
release.  The text of the first line should match this regexp:

@example
XEmacs \d+\(?:\.\d+\)+\(?:-b\d+\)?\(?:"\(\w\|\s-\)+"\)? is released
@end example

@node Tagging Releases, Creating Tarballs, Updating ChangeLogs, File Releases
@section Tagging Releases

@cindex tags
@cindex Mercurial, tag
@cindex version numbers

It is critical that a snapshot of the software is created each time
the software is released.  With Mercurial, this is performed with tags.

Every series of stable releases must have a branch tag of the form
@i{release-M-N}.  The trunk has no branch tag.  Every release must have
a fixed tag of the form @i{release-M-N-B}, where @var{M} is the major
number, @var{N} is the minor number, and @var{B} is the beta release or
patch number.  A hyphen is used for historical reasons.

The stable release branch tag doubles as a tag of the most recent
release.  While this is not quite true during the process of
accumulating patches to the branch, due to the conservative nature of
that process it seems very unlikely to cause trouble.  Since the trunk
has no tag, and many beta testers would prefer to avoid checking out in
the middle of a series of related check-ins, a fixed tag of the form
@i{release-M-N-current-beta} is used to identify the current beta
release.  It is updated by a command like @samp{cvs rtag -F -r
release-M-N-B release-M-N-current-beta}.

The packages have independent release schedules, determined by the
XEmacs package maintainer and the XEmacs Package Release Engineer.


@node Creating Tarballs, Creating @value{XEMACSORG} Releases, Tagging Releases, File Releases
@section Creating Tarballs

@cindex Creating Tarballs
@cindex modules
@cindex tarballs, naming


@cindex tarballs, making
@cindex tarballs, naming
@cindex tags
@cindex Mercurial, tags
@cindex Makefile targets, dist
@cindex version numbers

@strong{Write me!}

@node Creating @value{XEMACSORG} Releases, Updating the Tracker, Creating Tarballs, File Releases
@section Creating @value{XEMACSORG} Releases

@cindex Creating @value{XEMACSORG} Releases
@cindex releases
@cindex tarballs, making

@strong{Write me!}

@node Updating the Tracker, Announce the Release, Creating @value{XEMACSORG} Releases, File Releases
@section Updating the Tracker

@cindex Updating the Tracker

@strong{Write me!  (and install a Tracker!)}


@node Announce the Release, Updating the Emacs Repository, Updating the Tracker, File Releases
@section Announce the Release

@cindex Announce the Release

Now that the release is ready for download, announce it as described
in @xref{News}.

@node Updating the Emacs Repository, Updating the Debian Package, Announce the Release, File Releases
@section Updating the Emacs Repository

@strong{Needs review.  Although on the face of it this obviously has
nothing to do with XEmacs, in fact there are probably hints here for
XEmacs release engineers.}

@cindex Updating the Emacs Repository
@cindex Emacs, updating

The Emacs repository is updated by the project
admin.  Other developers may skip this section.

The project admin must have an account on the @i{gnu.org} machines,
and must also be given access to the Emacs CVS repository.  This can be
accomplished by following these steps:

@enumerate

@item
Obtain a
@uref{https://savannah.gnu.org/account/register.php, Savannah login}.

@item
Become an Emacs developer by contacting one of the admins listed on
the @uref{https://savannah.gnu.org/projects/emacs/, Emacs main page}.

@item
Follow the instructions given in
@uref{https://savannah.gnu.org/cvs/?group=emacs, the CVS instructions}.

@end enumerate

@cindex emacs-devel
@cindex mailing lists, emacs-devel
@cindex mailman

The project admin must also join the @i{emacs-devel} mailing list.
Send a note to @i{emacs-devel-request@@gnu.org} or use the
@uref{http://mail.gnu.org/mailman/listinfo/emacs-devel, Mailman
interface} to subscribe.

This procedure must be performed before any changes have been made to
the XEmacs source since the release.  This can be easily accomplished in
by checking out the module with a sticky tag and should be done in any
case.

First, check out the Emacs source:

@example
    cvs -d $USER@@savannah.gnu.org:/cvsroot/emacs co emacs
@end example

If the Emacs source has already been checked out, ensure that the XEmacs
source is not locally modified.  This is essential for the next step to
proceed accurately.  If the install-emacs step described below had been
performed during testing leading up to the release, remove the
modified XEmacs files and run @code{cvs update} again.

@cindex import-emacs
@cindex Makefile targets, import-emacs

Next, ensure that there have not been any upstream changes to either
the source or documentation.  If so, the changes will need to be
imported into the @file{src} and @file{doc} modules.  This is done by
running:

@example
    make import-emacs
@end example

@cindex EMACS_HOME
@cindex environment variables, EMACS_HOME
@cindex variables, EMACS_HOME
@cindex install-emacs
@cindex Makefile targets, install-emacs

Then install the sources with:

@example
    cd src
    make install-emacs
@end example

The @code{install-emacs} target copies the lisp files to
@file{$EMACS_HOME/lisp/mh-e} and copies @file{NEWS} to
@file{$EMACS_HOME/etc}.

@cindex EMACS_HOME
@cindex environment variables, EMACS_HOME
@cindex variables, EMACS_HOME
@cindex install-emacs
@cindex Makefile targets, install-emacs
@cindex ChangeLog

Next, install the documentation with:

@example
    cd doc
    make install-emacs
@end example

This target copies @file{mh-e.texi} to @file{$EMACS_HOME/man}.

Update @code{$EMACS_HOME/etc/ChangeLog} and
@code{$EMACS_HOME/man/ChangeLog}.  Simply cite the XEmacs release.  For
example:

@example
    * NEWS, NEWS: Upgraded to XEmacs version 6.1.
@end example

and

@example
    * mh-e.texi: Upgraded to XEmacs documentation version 1.3.
@end example

Update @code{$EMACS_HOME/etc/NEWS} by adding text similar to the
following:

@example
    * Changes in Emacs 21.4

    ** XEmacs changes.

    Upgraded to XEmacs version 6.1.  Upgraded to XEmacs manual version 1.3.
    See NEWS for details.
@end example

It's possible that the update occurs before Emacs had been released
with a previous version of XEmacs; in this case, simply bump the version
number in the text above rather than add an entire new stanza.

Then check in the files like this:

@example
    cvs ci -m"Upgraded to XEmacs version 6.1.
              See etc/NEWS and lisp/mh-e/ChangeLog for details."
@end example

@cindex emacs-devel
@cindex mailing lists, emacs-devel

Send a note to @i{emacs-devel@@gnu.org}, with a cc to
@i{xemacs-design@@xemacs.org} with the details.  The subject
should indicate that the software has been checked in:

@example
    XEmacs 7.4.4 checked in
@end example

The first paragraph should include the description on the
@uref{https://sourceforge.net/projects/mh-e/, Summary} page, and the
text:

@example
    Read on for more details.
@end example

The second paragraph should contain:

@example
    Project home page at: http://mh-e.sourceforge.net/.
@end example

Finally, append the release notes.  If only the manual is updated, then
the announcement should read closer to the one used in the @value{XEMACSORG}
news item.

After checking XEmacs into Emacs, run @code{make import-emacs} a second
time to put the new code on the Emacs branch.  This makes it possible
to detect changes to XEmacs that an Emacs developer may make later.


@node Updating the Debian Package, Updating the XEmacs Package, Updating the Emacs Repository, File Releases
@section Updating the Debian Package

@cindex Updating the Debian Package
@cindex Debian Package, Updating
@cindex Debian

@strong{Edit me!  Or maybe not: currently the various distros have
their own maintainers.  It might be useful for Debian/Ubuntu because of
the complex Debian Emacs policy.}

To build a Debian package, you'll need to have installed the Debian
package @code{build-essential} as well as those listed in the
@code{Build-Depends-Indep:} line of the file @file{debian/control}.
Currently, there are the packages @code{debhelper} and @code{texinfo}.
The package @code{fakeroot} is also used below and @code{dpkg-dev-el}
is also useful.

@example
    apt-get install build-essential fakeroot debhelper texinfo dpkg-dev-el
@end example

Run the following commands from the top of the CVS tree to clean up the
tree of backup files and make a source tar file:

@example
    rm `find . -name "*~"`
    debian/rules source
@end example

This will make a new file such as @code{mh-e_7.0.orig.tar.gz}.  Unpack
it in a working directory and step into its top directory.  Edit the
first line of the file @file{debian/changelog} to change the version
number between parentheses to something appropriate (e.g.
@code{7.0.+cvs-0}), or add another entry to the changelog and edit the
version number.  If you installed the package @code{dpkg-dev-el} above,
simply do @kbd{C-c C-v} to insert this block and @kbd{C-c C-f} to
finalise the entry when done editing the version number.

You can then create a Debian package by running:

@example
    fakeroot debian/rules binary
@end example

This creates @file{../mh-e_7.0.+cvs-0_all.deb} which can be installed
using standard Debian package management:

@example
    dpkg -i ../mh-e_7.0.+cvs-0_all.deb
@end example

@node Updating the XEmacs Package, Updating the Online Documentation, Updating the Debian Package, File Releases
@section Updating the XEmacs Package

@cindex Updating the XEmacs Package
@cindex XEmacs Package, Updating
@cindex XEmacs

This task is the duty of XXX <@i{XXX}>.  It may be useful to others to
want to make an unofficial package of the CVS tree.

The rest of this section needs to be completed.

@node Updating the Online Documentation, Updating the Free Software Directories, Updating the XEmacs Package, File Releases
@section Updating the Online Documentation

@strong{Adrian, please review.}

@cindex Updating the Online Documentation
@cindex online documentation, updating
@cindex documentation, updating online
@cindex bitbucket.org
@cindex Mercurial, use in web site

The entire XEmacs web site is kept in a Mercurial repo on Bitbucket,
and automatically rebuilt by the commit trigger.

Thus, the basic procedure is similar to working on XEmacs source code.

@enumerate
@item
Check out the @samp{xemacsweb} module.

@item
Make the needed changes.

@item
Update the ChangeLog(s).

@item
Test the changes with @code{make} to ensure that all @file{genpage}
commands are correct.  Then use @code{make validate} to check that the
produced HTML is reasonably correct.

@item
Commit and push the workspace.
@end enumerate

The XEmacs online documentation is mostly written in the @file{genpage}
language, which ensures a consistent interface for internal links via
special commands processed by the @code{genpage} script, and a
consistent overall format enforced by use of template files.  Some of
the material, such as the online versions of the @emph{XEmacs User's
Guide} is generated directly from Texinfo, and checked in as HTML
rather than @file{genpage} source.

The validator used by @code{make validate} is based on the PSGML
package.  It is not perfect, but it is more convenient than the more
accurate online validators provided by the W3C and others.  The
webmaster should use the online validators and link checkers regularly.



@node Updating the Free Software Directories, After the Release, Updating the Online Documentation, File Releases
@section Updating the Free Software Directories

@strong{Add FreshMeat, at least.}

Update the @i{source-tarball} and @i{version} fields in the FSF/UNESCO
Free Software Directory (@pxref{Free Software Directories}), as well as
the @i{touched} field.  Update any other fields as necessary, including
the @i{updated} field.

@node After the Release,  , Updating the Free Software Directories, File Releases
@section After the Release

@cindex After the Release

After the release is complete, add the string @code{+cvs} to the
version number.  @xref{Updating Version Number}.

Then, define the next release.

Each developer goes through the bugs and feature requests and chooses
a month's worth of work for him to do.  For each selected item, he
increases the priority to 7 and assigns the task to himself.  Another
guideline for release size is that releases should only include 7 +/-
2 new features or bug fixes.

The first month should be full of fervent activity.  Development should
slow down in the second month while the new features are fine-tuned.
The third month is devoted to the release.  @xref{Release Schedule}.  It
is acceptable and often desirable to shorten each step in this cycle
in order to keep the number of release note bullet items to 7 +/- 2,
but in order to keep the releases fresh, it's probably not a good idea
to lengthen the process.

If a new bug or feature arises that a developer wants to work on, the
developer sets the priority of that item to 7 and resets the priority
of one of his other items back to 5.  This keeps the release from
growing without bound.

The motivation for this schedule is to keep the iteration cycle short,
to keep from adding new features just before a release, and from the
user's point of view, to increase the timeliness and quality of
releases.  It also limits the scope of the release, and makes it clear
when we're done.

@node News, Surveys, File Releases, Nodes borrowed from other projects not adapted to XEmacs
@chapter News

@strong{Needs review.}

@cindex News

@cindex xemacs-announce
@cindex mailing lists, xemacs-announce
@cindex emacs-devel
@cindex mailing lists, emacs-devel

Announcements about new releases are submitted
@uref{http://sourceforge.net/news/?group_id=13357, at @value{XEMACSORG}}, to
@i{xemacs-announce@@lists.sourceforge.net}, and to
@i{emacs-devel@@gnu.org}.  The @i{emacs-devel} list should not be used
for contrib releases, however.

The document
@uref{https://sourceforge.net/docman/display_doc.php?docid=12834&group_id=1,
Using Project News with Step-by-Step Instructions} is helpful when
composing your news item.

In all cases, use the following template for the subject:

@example
    XEmacs m.n.p released
    XEmacs contributed software m.n.p released
    XEmacs manual m.n.p released
@end example

As only the first paragraph is shown on the @value{XEMACSORG} front page, it
should be written wisely.  Emulate the look and feel of previous news
postings.  The first sentence should be the same as the first sentence
in the description on the home page.  The
following sentences are typically copied from the first paragraph of
the release notes and should briefly describe the benefit of the
release or otherwise entice the reader to read further.  The contrib
and doc releases, which do not have release notes, should include a
sentence or two which summarizes the release.  The last sentence of the
first paragraph should read:

@example
    Read on for more details.
@end example

Finally, include the release notes from @file{NEWS}.  Because the
introductory paragraph was already used, include the release notes
starting with the ``New Features'' item.  To avoid ugly wrapping, first
make every paragraph one line by copying the release notes into a
scratch buffer, setting the fill column to some very large number, and
running @code{fill-region}.

For contrib and doc releases, use the ChangeLog entries since the last
release.

Note that your news posting may be shown on the @value{XEMACSORG} front
page, so discretion is advised.

The announcement that is sent to the @i{xemacs-announce} mailing list
doesn't have the same first-paragraph restrictions as does the
@value{XEMACSORG} news item.  Therefore, the announcement should contain the
text:

@example
    Project home page at: http://www.xemacs.org/.
@end example

followed by the release notes.  However, the announcement for contrib
and doc releases, which lack release notes, should be closer to the
news item.

The Emacs announcement is described in @ref{Updating the Emacs
Repository}.

@node Surveys, Free Software Directories, News, Nodes borrowed from other projects not adapted to XEmacs
@chapter Surveys

@strong{Interesting.  Should we do this, maybe?}

@cindex Surveys

The project admin may create
@c #### need to fix the group_id
@uref{https://sourceforge.net/survey/?group_id=, Surveys}.  The
interface is backwards.  First you create questions and note the
question IDs.  Then you create a survey and list the question IDs.

@node Free Software Directories, , Surveys, Nodes borrowed from other projects not adapted to XEmacs
@chapter Free Software Directories

@cindex FSF/UNESCO Free Software Directory
@cindex Free Software Directories
@cindex Software Directories

The @uref{http://www.gnu.org/directory/, FSF/UNESCO Free Software
Directory} contains a description of all of the free software, including
@uref{http://www.gnu.org/directory/XEmacs.html, XEmacs}.  It must be
updated when there is a release of XEmacs, or when a significant new
feature has been added which should be advertised.

This entry is the master for the short and long descriptions of XEmacs
in various places.  These items should be updated each time the master
entry is modified.

In order to update the entry, first
@uref{http://savannah.gnu.org/cvs/?group_id=32, check out} the
directory via anonymous CVS:

@example
cvs -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/directory login
cvs -z3 -d:pserver:anoncvs@@subversions.gnu.org:/cvsroot/directory co directory
@end example

or CVS via SSH:

@example
cvs -z3 -d <membername>@@subversions.gnu.org:/cvsroot/directory co directory
@end example

Then make the desired changes to @file{XEmacs.txt}.  Next, update the
@i{touched} field.  If the changes were significant enough to be
announced, update the @i{updated} field as well.  For a description of
each field, see the @uref{http://www.gnu.org/gnulist/README, README}.

Send the patch to @i{bug-directory@@gnu.org}.  For more information,
see the @uref{http://www.gnu.org/help/directory.html, instructions}.

Finally, if any changes were made to the short or long descriptions, it
is likely that the following will have to be updated: the
@value{XEMACSORG} XEmacs project description (see
@uref{https://sourceforge.net/project/admin/editgroupinfo.php?group_id=13357,
Editing the @value{XEMACSORG} Project Description}), the top-level
@file{index.php} file in the Project Website (@pxref{Project
Website}), the @file{control} file in the Debian package
(@pxref{Updating the Debian Package}), and the XEmacs package
(@pxref{Updating the XEmacs Package}).

@c #### Nuke this, but check whether the topics below need discussion.

@c @node Miscellaneous Topics, Copying, Free Software Directories, Top
@c @chapter Miscellaneous Topics
@c 
@c This section contains a few items that should probably be deleted, but
@c are kept for completeness.
@c 
@c @menu
@c * Task Manager::                
@c * DocManager::                  
@c * Public Forums::               
@c * Anonymous FTP Space::         
@c @end menu

@node Index,  , Nodes borrowed from other projects not adapted to XEmacs, Top
@unnumbered Index

@printindex cp

@bye