Ubuntu Manpage: xemacs-devguide.texi

input texinfo @c -*-texinfo-*- @c $Id: xemacs-devguide.texi,v 1.6 2007-05-12 17:04:26 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.6 @set UPDATED 2007-02-17 @set UPDATE-MONTH February, 2007

@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 CVS-LIST the @email{xemacs-cvs@@xemacs.org,XEmacs CVS Notices} 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}.

@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:: * Nodes borrowed from other projects not adapted to XEmacs:: * Index::

@c @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:: * CVS 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:: * Copying::

Bugs

* Bugs:: * Category:: * Status:: * Group:: * Resolution:: * Support Requests:: * Feature Requests::

File Releases

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

Misc

* Copying::

@c @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 captures the philosophy of the development team. There is then a section for each resource in the @value{PROJECT} that developers may want to use or need to change.

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 user of the package system in 21, and Unicode support in 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.

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

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 @emph{is 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 a 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 even 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 and 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 CVS repository, 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 module containing a set of optional libraries with XEmacs. The module 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 CVS repository. @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, though very powerful. 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 CVS 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 CVS repository is 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 CVS 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 CVS 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 cvs.xemacs.org committer accounts

There are a few minor prerequisites to get out of the way. The first is to @email{cvs-manager@@xemacs.org,request an account at @i{cvs.xemacs.org}}, and 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/,XEmacs Lisp Manual} @ifinfo @xref{Top, XEmacs Lisp Reference, , lispref}. @end ifinfo as well as the @uref{http://www.xemacs.org/Documentation/,XEmacs Manual}. @ifinfo @xref{Top, XEmacs User's Guide, , xemacs}. @end ifinfo

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

If you think that you may contribute enough to want access to the CVS repository, request access from the @email{cvs-manager@@xemacs.org,CVS Administrator}. 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 CVS 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.

CVS ===

Getting hold of your code from CVS: ----------------------------------
CVS_RSH=ssh
cvs -z3 -d :ext:xemacs@@cvs.xemacs.org:/pack/xemacscvs co redtape

Which will get just the redtape package. You can get all the packages with the module name "packages". I'd strongly suggest that you get the whole packages tree as usually packages require some functionality from other packages. But be warned, the packages tree is quite big (120+ MB as of 2007/02).

Committing patches to CVS: -------------------------
My recommendation would be to use the excellent PCL-CVS
package. It makes life a whole lot easier.

Also, 'patcher.el' and 'patch-keywords.el' from the xemacs-devel package are both excellent libraries that can make things a lot easier for you when it comes to creating and submitting patches.

Building ========

For a quick start to building packages, see INSTALL under the packages/ dir you've checked out from CVS.

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 CVS 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 in CVS 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
- cvs diff -u > cool-new-patch.diff
- submit to xemacs-patches
- unless there are objections, or if it's "obviously correct",
commit to CVS

Us
- cvs update
- 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:: * 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 -modesthe 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, Advice to Package Maintainers, The Package Maintainer Role, XEmacs Package Maintainer @subsection Getting Started as a Package Maintainer

The first step is to check out the package from CVS in read-write mode. This is done as follows:

@example export CVSROOT=:ext:xemacs@@cvs.xemacs.org:/pack/xemacscvs export CVS_RSH=/usr/bin/ssh cvs checkout packages @end example

This will take a while, and about 120MB 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. Unless one is really really tight for space, it's best to start by just checking out the whole thing, and prune it back later.

The package developer is welcome to change anything in the subtree that contains the 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 (with the above environment settings)

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

which is a good test that everything is working. You can find out more about CVS and the XEmacs repository at @url{http://cvs.xemacs.org}.

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

Then copy the updated upstream files over the existing ones. Try making a package with make bindist. Use the new code, too, to see if you find any bugs. If not, you can commit the new files to CVS.

When you make a commit, 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 @var{cvsuser}@@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 Advice to Package Maintainers, , Getting Started as a Package Maintainer, 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 with @kbd{cvs update -dP} 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 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 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 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 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 CVS trunk. 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 (specifically the GNU Emacs project), 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 (in particular, GNU Emacs), 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

@strong{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 it 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 CVS trunk). 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

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 SSH key, and ask one of the CVS maintainers (currently Adrian Aichner, Norbert Koch, and Stephen Turnbull, mail alias cvs-manager@@xemacs.org) to add the key to the authorized_keys file for the xemacs account at SunSITE.

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 cvs.xemacs.org. If you have any trouble due to extensions of your permissions, let the CVS Managers know at cvs-manager@@xemacs.org. The directions at

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

seem to be pretty clear.

XEmacs uses facilities at Tux.org (mailing lists, FTP archive, and web site) and at SunSITE.dk (CVS repository, web site). 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 these resources, let me know (for Tux) or Adrian (for SunSITE). The administrators on both sites 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 CVS, tagging CVS, 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 (actually, the CVS trunk).

@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 CVS 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.

@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{cvs diff -uN} 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{cvs diff -U 0 ChangeLog}, or submitted as plain test.

@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; not required.

@item Commit the patch. Who commits, how to commit, and when to commit.

@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 do that.)

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 @samp{xemacs} module from the CVS repository @ref{CVS 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. It's true that CVS has problems in advanced usage, but for these simple housekeeping tasks it works very well. Use CVS.

@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. 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 CVS 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

For consistency, phrase the issue number as follows (@pxref{Updating NEWS}):

@example
(closes SF #621632). @end example

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

The Emacs 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 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. @strong{Is this appropriate for XEmacs?}

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. In pcl-cvs, you can simply hit @kbd{C} (@code{cvs-mode-commit-setup}) and you'll get a buffer in @code{log-edit-mode} initialized with the appropriate entries from the change log. Or, you can suck in the change log entries with @kbd{C-c C-a} (@code{log-edit-insert-changelog}) if you use VC.

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

(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 CVS. 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 or recent CVS versions is strongly preferred (except for @file{ChangeLog}; see below). @strong{N.B.} If you use older diffs or CVS (eg, version CVS 1.10), 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 1, 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.

Didier Verna's @file{patcher.el} is an excellent utility for creating patches for submission to XEmacs. It can also submit the patch and commit the changes to CVS as appropriate.

@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 CVS module 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

Didier Verna's @file{patcher.el} is an excellent utility for creating patches for submission to XEmacs. It can also submit the patch and commit the changes to CVS as appropriate.

@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 CVS 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 is currently some 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 checked in to CVS as soon as possible. The committer should prepare a commit message using the keyword @samp{COMMIT} as a reply to the approval message. (In the case of @emph{commit-and-review}, there is no way to reply, so this requirement is meaningless.) The CVS log message should refer unambiguously to the @samp{COMMIT} message, preferably via the RFC 2822 message ID. (The mailing list archives may lag up to 24 hours, so using an URL is infeasible.)

@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 CVS 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. (2005-01-20)}

@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). @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} @ref{CVS Repository}. There should also be a node for the Emacs Wiki.}

@cindex XEmacs Resources on the Internet

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

@node Project Website, CVS 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 @ref{CVS Repository}, 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 CVS Repository, comp.emacs.xemacs, Project Website, XEmacs Resources on the Internet @section CVS Repository

@cindex CVS Repository

@c #### update the specific links for convenience!! The @uref{http://cvs.xemacs.org/,CVS Repository} contains several modules. You can view the repository with ViewCVS from a link on repository's home page, and there is a link to an explanation of how to use CVS in the CVS Repository.

@node comp.emacs.xemacs, xemacs-beta, CVS 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

@strong{Write me!}

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

@strong{Write me!}

@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 @ifinfo @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION @end ifinfo

@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 @ifinfo @center NO WARRANTY @end ifinfo

@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 @ifinfo @center END OF TERMS AND CONDITIONS @end ifinfo

@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, , Top @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, Top @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, Top @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, Top @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, Top @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 (@pxref{CVS Repository}), 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 date of a CVS checkout.

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 +.++-b+?"s-+"? is released @end example

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

@cindex tags @cindex CVS, tag @cindex version numbers

It is critical that a snapshot of the software is created each time the software is released. In CVS, 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 since one cannot use dots in CVS tag names.

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 CVS Repository @cindex modules @cindex CVS, modules @cindex tarballs, naming

The modules in the CVS Repository (@pxref{CVS Repository}) map to the distribution tarballs as follows:

@quotation @multitable @columnfractions .4 .6

@item @strong{Module} @tab @strong{Tarball}

@item Full distro @tab xemacs-X.Y.Z.tar.gz

@item Patch @tab xemacs-X.Y.Z-X.Y.(++Z).patch.gz

@item Sources only @tab xemacs-X.Y.Z-src.tar.gz

@item Compiled Lisp @tab xemacs-X.Y.Z-elc.tar.gz

@item Formatted Info @tab xemacs-X.Y.Z-info.tar.gz

@end multitable @end quotation

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

The tarballs listed in the table above are built as follows:

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

@cindex gnu.org @cindex CVS Emacs Repository @cindex Emacs CVS Repository @cindex Savannah

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:

@table @emph

@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 table

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

@cindex CVS, co

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 CVS, update

The entire XEmacs web site is kept in CVS, 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 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 to CVS 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, Top @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, Top @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, Top @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

Ubuntu Manpages

xemacs-devguide.texi