The XEmacs Developers Guide
***************************

This is Edition 0.8.1 of the XEmacs Developer's Guide, last updated 2015-12-03.

Copyright © 2000, 2001, 2002, 2003, 2004 Bill Wohler

Copyright © 2005, 2007 Free Software Foundation

     The XEmacs Developer's Guide 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 XEmacs Developer's Guide 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.

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

Acknowledgments
***************

Special thanks go to Bill Wohler, whose 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.

Introduction
************

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

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

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

And remember, this is your document.  If you think something is bogus, start a movement on the XEmacs Beta mailing 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.

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

Feel free to submit patches to the XEmacs Patches mailing list.  Please try to review and edit a whole node at a time.  They're short; it's not that great a burden.

Philosophy
**********

This node has a fair amount of content almost
unchanged from the MH-E Developers Guide, and is not fully
representative of the XEmacs 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.

Code
====

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

 1. Keep the C code fast.

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

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

 4. XEmacs should be easy to use out-of-the-box for new users.

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

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

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

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

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

Guiding Principles
==================

The guiding principles of the XEmacs developers are:

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

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

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

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

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

 6. Finally, we're here to have fun.

Coding Conventions
==================

Coding conventions are described in detail elsewhere. See Internals Manual (internals).

Here are a few additional references that you might want to check out.

The (GNU) Emacs Lisp Manual Tips and Conventions (elisp).

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

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

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

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

The GNU Coding Conventions (http://www.gnu.org/prep/standards.html) is required reading.  Note that XEmacs has its own slightly different, version.  See Coding Standards (standards).

Before checking in files, load lisp-mnt into Emacs, and run lm-verify within the lisp file you are editing to ensure that all of the fields described in Library Headers (elisp), are present.  The checkdoc function should be run before check-ins as well.  All errors must be fixed.

You should also read the comments in the 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.

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.

People and the Project
======================

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

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

Here are some of the better defined roles.  Most are defined by reference to XEmacs Project resources.

Developer
Contributor
     You.  Me.  Generally, anybody who wants to help improve XEmacs. See The Work Flow.

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. See XEmacs Resources on the Internet.

Beta tester
     A user currently not active as a code contributor, but willing to reinstall XEmacs or its packages regularly, and report any problems. Should participate in the XEmacs Beta mailing list.  See xemacs-beta.

Committer
     A developer with write access to the XEmacs repositories, which may be restricted to specified modules.  See Committer.  Should participate in the XEmacs Beta mailing list xemacs-beta, and the XEmacs Patches mailing list xemacs-patches.

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

Reviewer
     A developer who may authorize developers, including himself, to write to the XEmacs repositories.  See XEmacs Reviewer.  Should participate in the XEmacs Beta mailing list xemacs-beta, the XEmacs Patches mailing list xemacs-patches, and the XEmacs Review mailing list xemacs-review.

XEmacs Review Board
     The reviewers as a group, responsible for delegating access to XEmacs Project resources to developers.  A self-selecting cabal.  The current members are noted on the Jobs List (http://www.xemacs.org/Develop/jobs.html). See Jobs List.

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

Meta-maintainer
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 the comp.emacs.xemacs Usenet newsgroup comp.emacs.xemacs and the XEmacs Beta mailing list xemacs-beta.

Release engineer
Stable release engineer
Package release engineer
     Responsible for the quality control and adminstrative details of distributing some coherent package of functionality.  The stable release engineer manages the core distribution, including the build infrastructure, the Lisp and display engine, and the functions typical of a programmer's editor.  The package release engineer manages the various unbundled applications, the build infrastructure, and the network-based download and install functionality for them.  Must participate in the XEmacs Patches mailing list xemacs-patches.

Postmaster
Webmaster
Repository Manager
     Administrators of the various Internet-based services important to XEmacs users and developers.

Miscellaneous
     The Jobs List describes a number of other idiosyncratic positions and tasks in the XEmacs Project.  It also lists the current members of the XEmacs Review Board.  See Jobs List.  The most recent version can be found on the website (http://www.xemacs.org/Develop/jobs.html).

Beta Tester
===========

An extremely important role is that of beta tester.  Since the XEmacs repositories are open for anonymous read access, beta testers do not get special access to unpublished code.  Rather, beta testers 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 the XEmacs Beta mailing list, preferably via M-x report-xemacs-bug RET. the XEmacs Beta mailing list is also the channel to lobby for their favorite new features. Build reports are submitted to the XEmacs Build Reports mailing list via the 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.

Committer
=========

A committer is one who is authorized to check in approved changes into the source repository, including changes to private branches they may maintain.  Note that, in contrast to the use of this term on many projects, being a committer is simply an administrative convenience; committers must wait for approval to check in changes. Developers who do not have repository write access contribute by submitting patches to the XEmacs Patches mailing 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.

Commit Access
-------------

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

Developers should be familiar with the XEmacs Lisp Manual (http://www.xemacs.org/Documentation/21.5/html/) See XEmacs Lisp Reference (lispref). as well as the XEmacs Manual (http://www.xemacs.org/Documentation/21.5/html/). See XEmacs User's Guide (xemacs).

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

On a less serious note, the about-xemacs command gives information, including photos, about developers past and present. Submit a patch to lisp/about.el and an image that represents you (as both a monochrome PNG and a color PNG) to the XEmacs Patches mailing list.

Committer Welcome Message
-------------------------

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

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

     Hi Newbie!

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

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

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

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

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

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

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

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

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

     Building
     ========

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

     Patches
     =======

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

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

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

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

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

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

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

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

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

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

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

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

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

     Oldbert Reviewer,
     XEmacs Package Release Manager.

XEmacs Package Maintainer
=========================

A special kind of committer is the 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 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. See 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 RECOMMEND patches that they like.  See Patch Review.

In other words, each unbundled package, in principle, has a separate development organization.  It may be hosted by the XEmacs 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 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.

The Package Maintainer Role
---------------------------

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

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

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

Getting Started as a Package Maintainer
---------------------------------------

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

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

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

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

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

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

     default=ssh://hg@bitbucket.org/xemacs/PACKAGE_NAME

For https, change the default line in the .hg/hgrc for each package to

     default=https://LOGIN@bitbucket.org/xemacs/PACKAGE_NAME

where LOGIN is your Bitbucket login name.

The package developer is welcome to change anything in the repo for his or her package.  However, there are a couple of administrative files that are conceptually the "property" of the package system.  These are package-info.in and the Makefile.  There is almost surely no need to change either at this time, except to change the MAINTAINER variable in the Makefile to contain the maintainer's name and email address.  The package maintainer should never change the 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 AUTHOR_VERSION variable in sync with upstream, if that makes sense.  It may be possible and convenient to have AUTHOR_VERSION == VERSION; ask the package release engineer about it if that seems attractive.

So now you can

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

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

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

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

When you push a change to the master packages repository, you should notify the package release engineer, currently 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 @xemacs.org. The package maintainer addresses are

     FIRSTNAME.LASTNAME@xemacs.org

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

     PACKAGE-bugs@xemacs.org
     PACKAGE-discuss@xemacs.org
     PACKAGE-patches@xemacs.org
     PACKAGE-maintainer@xemacs.org

The last alias is set to the maintainer address.  The bugs- and discuss- aliases are redirected to XEmacs Beta, and the 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.

Updating and Merging with Mercurial
-----------------------------------

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

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

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

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

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

Committing and Pushing a Package Change
---------------------------------------

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

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

Updating a Package to a New Upstream Version
--------------------------------------------

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

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

 1. Diff the new upstream version against the previous upstream version to generate a patch file.

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

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

 4. Apply the patch and resolve any conflicts by hand.

 5. Manually register any new files with Mercurial (hg add) and remove any files that have been deleted (hg rm --after).

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

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

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

ChangeLog files
===============

Many upstream packages provide their own ChangeLog files.  You may wish to rename those to ChangeLog.upstream (or some variation), so that they are separate from the XEmacs ChangeLog files.  You can refer to the upstream ChangeLog file in the ChangeLog entry that you create when updating to a new upstream release.  For example:

         YYYY-MM-DD  J. Random Hacker  <jrh@xemacs.org>

         	* Sync with foobar 2.7.
         	Please see the ChangeLog.upstream files for details.

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. I.e., the maintainer of an editor mode.

Setting Up to Build Your Package
================================

Building a package almost always requires the presence of the source code for other packages.  Almost all packages depend on the xemacs-base package, for example.  Therefore the recommended procedure is to check out the whole package tree, configure Local.rules, and do a full build with make from the top. (After that you should keep the tree up-to-date, see Updating and Merging with Mercurial, and occasionally do a make to keep things in order.)  Having done this once, you can thereafter normally simply do make and 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 are welcome, but they must account for the need to provide macro definitions and autoloads.

Cloning from your local copy
============================

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

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

and then run the following script.  In the example above, you would run it from the mypackages/xemacs-packages directory.

     #! /bin/sh
     top=$(basename $(pwd))
     for d in mule-packages xemacs-packages; do
       for f in $d/*; do
         [ -d $f ] && ln -s $top/$f ..
       done
     done
     mv ../Sun ../sun
     mv ../hm--html-menus ../hm-html-menus

Lisp macros and autoloads
=========================

Lisp provides macros, which involve 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 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, 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 defsubst is like C 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 autoload facility allows definitions to be loaded the first time they are used.

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 REQUIRES Make variable are required, and the autoload definitions are loaded from generated libraries called auto-autoloads in each package.

So you should at least do 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.

Maintaining Package Metadata
============================

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

To update the packages that your package depends on, edit the REQUIRES list in the package's Makefile.

To update the list of libraries that your package provides, edit the provides clause in the package's package-info.in.

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.

XEmacs-Specific Changes
=======================

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

     ;; XEmacs change

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

Changes to Other Packages or Top-Level
======================================

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

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

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.

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

XEmacs Reviewer
===============

A reviewer is a developer who may approve or veto patches proposed for application to the XEmacs core code.  They are expected to subscribe to the XEmacs Patches mailing list, the channel for submission of patches to the XEmacs code base and documentation sources.  The collection of reviewers constitutes the XEmacs Review Board, which is responsible for arbitrating conflicts among reviewers, for relations to other projects, for changes to the development process described in this Guide, and for giving access to XEmacs Project resources to developers, including selecting new reviewers. Unlike many projects, the XEmacs Project does not have a single authoritative maintainer. Policy discussions are conducted on the the XEmacs Review mailing 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.

Appointing New Reviewers
------------------------

The XEmacs Review Board is a self-maintaining cabal.  New reviewers are appointed when the Board feels having a person as a colleague would improve the project.

Welcoming New Reviewers
-----------------------

When a new reviewer is appointed, a representative of the XEmacs Review Board (typically the meta-maintainer or the mentor of the new reviewer) sends a welcome message to the new reviewer.  Here's a sample.

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

     Dear Newbie,

     Welcome to the XEmacs Review Board.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     seem to be pretty clear.

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

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

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

Meta-Maintainer
===============

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

Release Engineer
================

A release engineer (also called release manager) is responsible for the administrative aspects of releasing a distribution, including such things as ensuring that generated files are committed to the repository, tagging the version in the repository, updating release documentation, creating and uploading tarballs, and making announcements.  Release engineers are 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.

There are currently three XEmacs release engineers: Vin Shelton, for the stable XEmacs 21.4 branch; Norbert Koch, for the XEmacs package distribution, and Stephen Turnbull, for the development 21.5 branch (the Mercurial xemacs branch).

Jobs List
=========

There are a number of auxiliary roles requiring special access to XEmacs 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 XEmacs Project, so definition will be postponed to the sections describing the roles in detail.  Many of these roles are listed in the Jobs List (http://www.xemacs.org/Develop/jobs.html).

The Work Flow
*************

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

The Life Cycle of a Patch
=========================

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

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

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

Add a ChangeLog entry.
     Tell us what you did.

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 hg diff against the tip of the branch or trunk you intend to have the patch applied to.  The exception is ChangeLog patches, which may be generated using hg diff -U 0 ChangeLog, or submitted as plain text.

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.

Review the patch.
     The primary function of the XEmacs Review Board is to help you improve your contributions.  We aim for coherence and power in the interfaces, and maintainability in the implementation.

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

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

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

About Copyright Assignment
==========================

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 XEmacs Project neither advocates nor discourages this action; it's up to you.

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

Get more information about procedures from the GNU Emacs developers' mailing list or from Richard Stallman.  You may also wish to review Information For Maintainers of GNU Software (http://www.gnu.org/prep/maintain.html), although it is not directly related to XEmacs Project procedures.

Scratching That Itch
====================

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.

Get the Sources
===============

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

Write Low-Profile Code
======================

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

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 users, we have the 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 forward-char takes an optional signed integer argument and there is no backward-char, other developers will likely be rather annoyed if you define separate forward-word and 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: minimize your patches.  This principle extends to the degree of violating coding standards in situations like the following example.

     {    /* new compound statement to enclose new_local_variable */
       int new_local_variable = initializer ();
     {    /* 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                   */
     }

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

Test Your Changes
=================

XEmacs provides a suite of regression tests which you can run with 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.

Add a ChangeLog Entry
=====================

Needs review!!

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

ChangeLogs
----------

This section is pretty close to correct for XEmacs.  Needs review.

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

Here is an example ChangeLog entry:

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

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 ChangeLog commands such as C-x 4 a (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.

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

         (closes issue1234).

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

         (closes SourceForge #621632).
         (closes Debian #234234).

The XEmacs manual has full documentation on the ChangeLog commands.

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

Log Messages
------------

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.

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

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

Note that the * 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 * and filenames will need to be present to separate the messages.

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

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

I specify the following for log-edit-hook to make life easier:

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

Log messages for files named ChangeLog may be empty.

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 reviewers only was adopted in first quarter 2005.)

Patches should be created using a standard diff(1) such as provided by GNU diffutils, or implemented by Mercurial.  A patch should be a 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 diff -urN format produced by GNU diff is strongly preferred (except for ChangeLog; see below).  N.B. If you use older diffs, please check for the presence of full relative paths in three places: the Index, ---, and +++ lines.  If the latter do not have the appropriate relative paths, patch(1) will invariably fail to find the target file, and the application will fail.

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

Submit the Patch
================

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

Send the patch by email to the XEmacs Patches mailing list.  The subject line should indicate the branch or package in square brackets at the beginning of the field.  Some developers like to include the keyword 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:

     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

The first line of the message may contain special keywords.  The only ones normally used by non-reviewers are SUPERSEDES and the module names.  The keyword SUPERSEDES must be used if the patch is intended to be applied instead of another addressing the same issue.  In this case the message 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 References header or an In-Reply-To header or both. Optionally, if it is difficult to do this for some reason, an URL pointing to the thread in the XEmacs Patches mailing list's archives, or (less desirable) the superseded patch's message ID, 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) 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:

     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]

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 XEmacs Review Board, may optionally omit the email submission. Instead, the responsible reviewer simply commits the patch, and the repository commit-trigger will automatically generate and post the patch to the XEmacs Patches mailing list.  This may be referred to as implicit
self-approval.

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)

Patch Review
============

(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 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 the XEmacs Patches mailing 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 reviewer action, which is a reply to the thread stating his formal decision.  The currently defined reviewer actions are

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

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

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.

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

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

There has been controversy on the XEmacs Review 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 VETO, the veto may be overridden by three votes for 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.)

Commit-and-Review
-----------------

A reviewer may self-approve his own submission.  In this case, the reviewer may use commit-and-review, that is, submit, approve, and announce the commit in a single post to the XEmacs Patches mailing 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 QUERY or VETO post their action within a week.  In the case of a VETO, the patch must be reverted immediately, pending an override or withdrawal of the veto.

Committing the Patch
====================

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

Proposed Alternative Procedure
------------------------------

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

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

Dispute Resolution
==================

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

There seems to be general agreement that XEmacs 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.

Only patches can be reviewed.

     And therefore, only patches can be vetoed.  People can propose, purely for discussion, whatever they like.  Such proposals 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 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 XEmacs Review 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.

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.

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 #ifdefs, 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 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.)

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.

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.

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 may refuse to revert, and in that case, the vetoer needs two concurring vetos.  This constitutes a blocking coalition of three---the patch must be reverted immediately, even if it seems likely that a vote of the board would back the commit.  The patch can be reapplied after the vote.

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

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

XEmacs Resources on the Internet
********************************

Write this node!  Get mailing list and newsgroup information from the mailing list page (http://www.xemacs.org/Lists/), available as the module xemacsweb.

There should also be a node for the Emacs Wiki.

Project Website
===============

Needs review.  Adrian?

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

To install your updates into the XEmacs Web space at XEmacs.ORG, simply check out the xemacsweb module, make your changes, and check it in.  The commit script takes care of generating the HTML and pushing the changes to the web servers' document spaces.

Mercurial Repository
====================

The Mercurial Repository contains several branches of the trunk (currently version 21.5).  You can view the repository with an ordinary browser on the HTTP URL.

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

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

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

The Usenet Newsgroup comp.emacs.xemacs
======================================

Write me!

The xemacs-beta Mailing List
============================

Write me!

The xemacs-design Mailing List
==============================

This list is currently inactive.  Traffic that used to go to the XEmacs Design mailing list should be directed to the XEmacs Beta mailing list instead.

Concerning content, write me!

The xemacs-patches Mailing List
===============================

Write me!

The xemacs-mule Mailing List
============================

Write me!

The xemacs-winnt Mailing List
=============================

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

The xemacs-review Mailing List
==============================

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

GNU GENERAL PUBLIC LICENSE
**************************

Version 2, June 1991

     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.

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.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

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

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

 2. 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:

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

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

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

     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.

 3. 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:

      a. 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,

      b. 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,

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

     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.

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

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

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

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

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

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

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

     NO WARRANTY

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

 12. 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 OF TERMS AND CONDITIONS

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.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  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.

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:

     Gnomovision version 69, Copyright (C) 20YY 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.

The hypothetical commands show w and show c should show the appropriate parts of the General Public License.  Of course, the commands you use may be called something other than show w and 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:

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

     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

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.

Nodes borrowed from other projects not adapted to XEmacs
********************************************************

Support Requests
****************

Support requests are made to the XEmacs Beta mailing list.  Developers should read the mailing list frequently, and after a period of inactivity, browse the recent archives (http://list-archive.xemacs.org/xemacs-beta/).

Bugs
****

We don't have a tracker.  We should.  Describe what it should look like here.

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

Developers should follow the 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 XEmacs.ORG.  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 XEmacs Review 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 reports (https://sourceforge.net/tracker/reporting/?atid=113357&what=tech&span=&period=lifespan&group_id=13357#b).  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 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.

Category
========

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

General

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

UI

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

MIME

     The MIME category is used for bugs that pertain to MIME.

Security

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

Documentation

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

Contrib

     The Contrib category is used for all bugs in the contributed software.

Status
======

The bug status is divided into four sections: Open, Closed, Deleted and Pending.

Open

     When bugs are initially created, they are marked Open.

     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 (see Feature Requests) but otherwise handled in the same way.

Closed

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

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

Pending

     You can set the status to 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.

Deleted

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

Group
=====

The bug group contains several items.  They include:

None

     Bugs are initially filed in this group.

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.

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.

Resolution
==========

A bug can appear in various states:

Accepted

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

Duplicate

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

Fixed

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

Invalid

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

Later

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

Out of Date

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

Postponed

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

Rejected

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

Remind

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

Wont Fix

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

Works For Me

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

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 been added within a ``reasonable'' amount of time, a member of the XEmacs Review Board may set the status to Closed and the group to Wont Fix.  XEmacs Review 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.

After incorporating the feature, update the feature request as described in the previous section (see Bugs).

Patch Queue
***********

Developers should check the XEmacs Patches mailing 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.

File Releases
*************

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

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.

Release Schedule
================

Totally bogus for XEmacs historical practice, probably totally unrealistic as future policy.

Here is a suggested schedule for a release:

     Time
     Milestone
     Description

     T-4 weeks
     Soft Freeze

     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.

     T-3 weeks
     Hard Freeze

     All P7 and higher bug fixes must be committed.
     P6 bug fixes should be committed.
     Testing continues.

     T-2 weeks
     Beta 1

     Cut beta release.
     Upload to XEmacs.ORG.

     T-1 weeks
     Beta 2

     Cut beta release.
     Upload to XEmacs.ORG.

     T-0 weeks
     Release!

     Cut release.
     Upload to XEmacs.ORG.

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

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

Release Prerequisites
=====================

The first thing to do is to check the code for coding convention compliance as described in section Philosophy.

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

Updating NEWS
=============

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

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

 1. Go to Bugs (https://sourceforge.net/bugs/?group_id=13357) 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).

 2. Repeat for Feature Requests (https://sourceforge.net/tracker/?atid=363357&group_id=13357).

 3. Run the release-utils --variable-changes PREVIOUS-TAG to produce a list of new and deleted variables suitable for inclusion in NEWS.

 4. Run C-h m in MH Folder and MH Letter modes in both the new and old versions to show the key binding changes.

 5. Search for [0-9][0-9][0-9][0-9][0-9][0-9] in the ChangeLog to get a list of SF numbers.

 6. Use the ChangeLog.

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.

         cvs log -rr21-4-20
         cvs diff -rr21-4-20

See section Updating ChangeLogs before checking in this file.

Updating 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 Updating ChangeLogs before checking in this file.

Updating Version Number
=======================

XEmacs version information is kept in the file ${srcdir}/version.sh.   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, ${srcdir}/version.sh must assign the empty value to emacs_is_beta.  The value ``0'' is assigned to emacs_beta_version.  The next even number (which is ``0'' in the case that emacs_major_version is bumped) is assigned to emacs_minor_version, and emacs_major_version is bumped if that was authorized by the XEmacs Review Board.  The codename 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.  The version information is the same as the stable release, except that emacs_minor_version is bumped to the next odd integer, and 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 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.

N.B. Release engineers should avoid disturbing the order of variables in ${srcdir}/version.sh.  The variables emacs_kit_version, infodock_major_version, infodock_minor_version, and infodock_build_version are used for version information of various non-XEmacs Project releases, and should be ignored.  Both of these features are unclean, but users' auxiliary tools (and some tools distributed by the XEmacs Project, including build.el and 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 xemacs_extra_name which is a string that is appended to the version string.  It is currently automatically updated, and used to identify the Mercurial changeset.

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

Updating ChangeLogs
===================

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

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

Tagging Releases
================

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

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

The stable release branch tag doubles as a tag of the most recent release.  While this is not quite true during the process of accumulating patches to the branch, due to the conservative nature of that process it seems very unlikely to cause trouble.  Since the trunk has no tag, and many beta testers would prefer to avoid checking out in the middle of a series of related check-ins, a fixed tag of the form release-M-N-current-beta is used to identify the current beta release.  It is updated by a command like 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.

Creating Tarballs
=================

Write me!

Creating XEmacs.ORG Releases
============================

Write me!

Updating the Tracker
====================

Write me!  (and install a Tracker!)

Announce the Release
====================

Now that the release is ready for download, announce it as described in see News.

Updating the Emacs Repository
=============================

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.

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

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

 1. Obtain a Savannah login (https://savannah.gnu.org/account/register.php).

 2. Become an Emacs developer by contacting one of the admins listed on the Emacs main page (https://savannah.gnu.org/projects/emacs/).

 3. Follow the instructions given in the CVS instructions (https://savannah.gnu.org/cvs/?group=emacs).

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

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

First, check out the Emacs source:

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

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 cvs update again.

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 src and doc modules.  This is done by running:

         make import-emacs

Then install the sources with:

         cd src
         make install-emacs

The install-emacs target copies the lisp files to $EMACS_HOME/lisp/mh-e and copies NEWS to $EMACS_HOME/etc.

Next, install the documentation with:

         cd doc
         make install-emacs

This target copies mh-e.texi to $EMACS_HOME/man.

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

         * NEWS, NEWS: Upgraded to XEmacs version 6.1.

and

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

Update $EMACS_HOME/etc/NEWS by adding text similar to the following:

         * Changes in Emacs 21.4

         ** XEmacs changes.

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

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:

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

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

         XEmacs 7.4.4 checked in

The first paragraph should include the description on the Summary (https://sourceforge.net/projects/mh-e/) page, and the text:

         Read on for more details.

The second paragraph should contain:

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

Finally, append the release notes.  If only the manual is updated, then the announcement should read closer to the one used in the XEmacs.ORG news item.

After checking XEmacs into Emacs, run 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.

Updating the Debian Package
===========================

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 build-essential as well as those listed in the Build-Depends-Indep: line of the file debian/control. Currently, there are the packages debhelper and texinfo. The package fakeroot is also used below and dpkg-dev-el is also useful.

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

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:

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

This will make a new file such as 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 debian/changelog to change the version number between parentheses to something appropriate (e.g. 7.0.+cvs-0), or add another entry to the changelog and edit the version number.  If you installed the package dpkg-dev-el above, simply do C-c C-v to insert this block and C-c C-f to finalise the entry when done editing the version number.

You can then create a Debian package by running:

         fakeroot debian/rules binary

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

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

Updating the XEmacs Package
===========================

This task is the duty of XXX <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.

Updating the Online Documentation
=================================

Adrian, please review.

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

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

 1. Check out the xemacsweb module.

 2. Make the needed changes.

 3. Update the ChangeLog(s).

 4. Test the changes with make to ensure that all genpage commands are correct.  Then use make validate to check that the produced HTML is reasonably correct.

 5. Commit and push the workspace.

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

The validator used by 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.

Updating the Free Software Directories
======================================

Add FreshMeat, at least.

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

After the Release
=================

After the release is complete, add the string +cvs to the version number.  See 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.  See 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.

News
****

Needs review.

Announcements about new releases are submitted at XEmacs.ORG (http://sourceforge.net/news/?group_id=13357), to xemacs-announce@lists.sourceforge.net, and to emacs-devel@gnu.org.  The emacs-devel list should not be used for contrib releases, however.

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

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

         XEmacs m.n.p released
         XEmacs contributed software m.n.p released
         XEmacs manual m.n.p released

As only the first paragraph is shown on the XEmacs.ORG 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:

         Read on for more details.

Finally, include the release notes from 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 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 XEmacs.ORG front page, so discretion is advised.

The announcement that is sent to the xemacs-announce mailing list doesn't have the same first-paragraph restrictions as does the XEmacs.ORG news item.  Therefore, the announcement should contain the text:

         Project home page at: http://www.xemacs.org/.

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 Updating the Emacs Repository.

Surveys
*******

Interesting.  Should we do this, maybe?

The project admin may create Surveys (https://sourceforge.net/survey/?group_id=).  The interface is backwards.  First you create questions and note the question IDs.  Then you create a survey and list the question IDs.

Free Software Directories
*************************

The FSF/UNESCO Free Software Directory (http://www.gnu.org/directory/) contains a description of all of the free software, including XEmacs (http://www.gnu.org/directory/XEmacs.html).  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 check out (http://savannah.gnu.org/cvs/?group_id=32) the directory via anonymous CVS:

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

or CVS via SSH:

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

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

Send the patch to bug-directory@gnu.org.  For more information, see the instructions (http://www.gnu.org/help/directory.html).

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