[general-docs] Developer's Guide is almost ready for beta

general-docs After a delay of well over a year, I've put the Developer's Guide into some kind of condition to be distributed. I've moved the probably controversial section on dispute resolution into a separate file. The rest codifies our consensus on procedure and best practices as I understand them. I think it's worth circulating, but it should be viewed as descriptive, not as policy. In particular, people should feel free to update or correct my misperceptions, and I don't think there's reason to solicit consensus unless experience shows that some point is flammable. There are lots of niggling details (like ＠refs) that need checking before adding it to the distributed package. Checking would be very welcome, but no need to chase down correct references if you don't feel like it, just let me know which ＠node and ＠ref were bad. I also plan to scarf the descriptions of the various mailing lists from the web for that section of the guide, move beta.texi into the guide, and things like that. Unless somebody thinks this is a bad idea in principle, I'll commit in a couple days. Note that until added to EXPLICIT_DOCS in the Makefile, this will not be part of the official package distribution. I do hope to do that shortly. Index: xemacs-packages/general-docs/ChangeLog =================================================================== RCS file: /Users/steve/Software/Repositories/cvs.xemacs.org/XEmacs/packages/xemacs-packages/general-docs/ChangeLog,v retrieving revision 1.16 diff -u -U 0 -r1.16 ChangeLog --- xemacs-packages/general-docs/ChangeLog 7 May 2005 12:23:53 -0000 1.16 +++ xemacs-packages/general-docs/ChangeLog 12 Aug 2006 13:26:18 -0000 ＠＠ -0,0 +1,19 ＠＠ +2006-08-12 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/xemacs-devguide.texi: Massive changes to conform to + XEmacs reality. + (Index): Sync function and variable indicies to concept index. + +2005-03-13 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/xemacs-devguide.texi: References to Debian removed. + +2005-01-30 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/xemacs-devguide.texi: New file based on MH-E's. + Index: xemacs-packages/general-docs/texi/xemacs/xemacs-devguide.texi =================================================================== RCS file: /Users/steve/Software/Repositories/cvs.xemacs.org/XEmacs/packages/xemacs-packages/general-docs/texi/xemacs/xemacs-devguide.texi,v retrieving revision 1.1 diff -u -r1.1 xemacs-devguide.texi --- xemacs-packages/general-docs/texi/xemacs/xemacs-devguide.texi 1 Feb 2005 16:08:35 -0000 1.1 +++ xemacs-packages/general-docs/texi/xemacs/xemacs-devguide.texi 12 Aug 2006 13:32:43 -0000 ＠＠ -1,20 +1,27 ＠＠ -\input texinfo ＠c -*-texinfo-*- -＠c $Id: xemacs-devguide.texi,v 1.1 2005/02/01 16:08:35 stephent Exp $ +\input texinfo ＠c -*-texinfo-*- + +＠c This file was originally derived from the MH-E Developer's Guide +＠c version: devguide.texi,v 1.38 2004/08/22 04:40:48 wohler Exp +＠c by Bill Wohler. There's no possibility of synching, but it's worth +＠c paying attention to changes in their practices IMO. -- stephen +＠c ＠c Generate HTML with: ＠c (shell-command "texi2html -number -monolithic xemacs-devguide.texi" nil) -＠c -＠c Preamble edited: stephen 2005-01-20 + ＠c %**start of header ＠setfilename ../../info/xemacs-devguide.info ＠settitle xemacs-devguide +＠syncodeindex vr cp +＠syncodeindex fn cp ＠c %**end of header ＠c Version variables. -＠set EDITION 0.5 -＠set UPDATED 2005-01-20 -＠set UPDATE-MONTH January, 2005 +＠set EDITION 0.9 +＠set UPDATED 2006-08-12 +＠set UPDATE-MONTH August, 2006 ＠c Other variables. +＠set GUIDE ＠emph{XEmacs Developers' Guide} ＠set XEMACSORG XEmacs.ORG ＠set PROJECT XEmacs Project ＠set HOMEPAGE ＠uref{http://www.xemacs.org/,XEmacs Project Website} ＠＠ -27,13 +34,16 ＠＠ ＠set PATCHES-LIST the ＠email{xemacs-patches＠(a)xemacs.org,XEmacs Patches} mailing list ＠set CVS-LIST the ＠email{xemacs-cvs＠(a)xemacs.org,XEmacs CVS Notices} mailing list ＠set BUILDREPORTS-LIST the ＠email{xemacs-buildreports＠(a)xemacs.org,XEmacs Build Reports} mailing list +＠set WINNT-LIST the ＠email{xemacs-winnt＠(a)xemacs.org,XEmacs Windows Port} mailing list +＠set VERSIONFILE ＠file{$＠{srcdir(a)}/version.sh} ＠copying This is Edition ＠value{EDITION} of the ＠cite{XEmacs Developers Guide}, last updated ＠value{UPDATED}. -Copyright ＠copyright{} 2000, 01, 02, 03, 2004 Bill Wohler -Copyright ＠copyright{} 2005 Free Software Foundation +Copyright ＠copyright{} 2000, 2001, 2002, 2003, 2004 Bill Wohler + +Copyright ＠copyright{} 2005, 2006 Free Software Foundation ＠quotation The ＠cite{XEmacs Developers Guide} is free documentation; you can ＠＠ -96,6 +106,7 ＠＠ * Philosophy:: * The Work Roles:: * The Work Flow:: +* Release Engineering:: * XEmacs Resources on the Internet:: Nodes borrowed from other projects, not adapted to XEmacs: ＠＠ -104,11 +115,10 ＠＠ * Bugs:: * Feature Requests:: * Patch Queue:: -* File Releases:: * News:: * Surveys:: * Free Software Directories:: -* Copying:: +* Copying:: Permissions for this document. * Index:: ＠detailmenu ＠＠ -169,50 +179,48 ＠＠ * Project Website:: * CVS Repository:: -* comp.emacs.xemacs:: +* The comp.emacs.xemacs Newsgroup:: +* XEmacs Mailing Lists:: + +XEmacs Mailing Lists + +* Maintaining the Mailing Lists:: * xemacs-beta:: * xemacs-design:: * xemacs-patches:: * xemacs-mule:: * xemacs-winnt:: -Nodes borrowed from other projects, not adapted to XEmacs - -Bugs - -* Category:: -* Status:: -* Group:: -* Resolution:: - -File Releases +Release Engineering * Release Schedule:: -* Release Prerequisites:: +* Release Prerequisites:: * Updating NEWS:: -* Updating README:: * Updating Version Number:: * Updating ChangeLogs:: * Tagging Releases:: * Creating Tarballs:: * Creating ＠value{XEMACSORG} Releases:: -* Updating the Tracker:: * Announce the Release:: -* Updating the Emacs Repository:: -* Updating the Debian Package:: -* Updating the XEmacs Package:: * Updating the Online Documentation:: * Updating the Free Software Directories:: * After the Release:: +Nodes borrowed from other projects, not adapted to XEmacs + +Bugs + +* Category:: +* Status:: +* Group:: +* Resolution:: + ＠end detailmenu ＠end menu ＠node Acknowledgments, Introduction, Top, Top ＠chapter Acknowledgments -＠c Edited: stephen 2005-01-18 - Special thanks go to Bill Wohler, whose ＠emph{MH-E Developers Guide} formed the framework for this document, and contributed a lot of text as well, for permission to redistribute the derived work under the GNU ＠＠ -227,8 +235,6 ＠＠ ＠node Introduction, Philosophy, Acknowledgments, Top ＠chapter Introduction -＠c Edited: stephen 2005-01-18 - ＠cindex Introduction ＠cindex ＠value{XEMACSORG} ＠＠ -286,14 +292,13 ＠＠ ＠node Philosophy, The Work Roles, Introduction, Top ＠chapter Philosophy -＠c Edited: stephen 2005-01-18 - ＠cindex Philosophy -＠strong{Currently pretty much everything in this node is hardly -representative of the ＠value{PROJECT}. Sometimes stephen thinks much of -this would be a good statement of values, other times he doesn't. What -do you think? Submit a patch!} +＠strong{Currently pretty much everything in this node is drawn from the +MH-E Developer's Guide, and is hardly representative of the +＠value{PROJECT}. Sometimes stephen thinks much of this would be a good +statement of values, other times he doesn't. What do you think? Submit +a patch!} This chapter discusses the philosophy and principles of the XEmacs project. The first section covers our coding philosophy, while the ＠＠ -421,7 +426,11 ＠＠ not. This will aid future project admins greatly if there ever is a merger.} -You ＠strong{must} reference the GPL correctly in every file. +You ＠strong{must} reference the GPL correctly in every file. If you +believe that an entire file can be placed in the public domain, or +under another license, you are quite possibly right. However, because +this is very unusual, it is very important to discuss this with the +＠value{BOARD} to ensure that your wishes are respected in the future. Manuals must also follow these rules, except that for historical reasons they have various different licenses. ＠emph{Be careful}: it is ＠＠ -437,11 +446,13 ＠＠ licenses are preferred. The ＠uref{http://www.gnu.org/prep/standards.html, GNU -Coding Conventions} is required reading. - -Before checking in files, load ＠file{lisp-mnt} into Emacs, and run -＠code{lm-verify} within the lisp file you are editing to ensure that -all of the fields described in +Coding Conventions} is required reading. The Info version distributed +with XEmacs is the preferred edition. Note that some GNU practices are +modified for XEmacs; please refer to the XEmacs Internals Manual. + +Before checking in Lisp files, load ＠file{lisp-mnt} into Emacs, and run +＠code{lm-verify} within the Lisp file you are editing to ensure that all +of the fields described in ＠ifnothtml ＠ref{Library Headers, , , elisp}, ＠end ifnothtml ＠＠ -463,8 +474,6 ＠＠ ＠node The Work Roles, The Work Flow, Philosophy, Top ＠chapter The Work Roles -＠c Created: stephen 2005-01-20 - 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 ＠＠ -534,7 +543,8 ＠＠ A developer who may authorize developers, including himself, to write to the XEmacs CVS repository. ＠xref{XEmacs Reviewer}. Should participate in ＠value{BETA-LIST} ＠ref{xemacs-beta}, ＠value{DESIGN-LIST} -＠ref{xemacs-design}, and ＠value{PATCHES-LIST} ＠ref{xemacs-patches}. +＠ref{xemacs-design}, ＠value{PATCHES-LIST} ＠ref{xemacs-patches}, as well +as ＠value{REVIEW-LIST} ＠ref{xemacs-review} (restricted to reviewers). ＠item XEmacs Review Board The reviewers as a group, responsible for delegating access to ＠＠ -555,7 +565,8 ＠＠ done, and finding someone to do it. The latter title allows him to tell his mother how important he is. More seriously, the meta-maintainer often functions as a spokesman for the Board or the project as a whole. -Should be highly visible on ＠value{C-E-X} ＠ref{comp.emacs.xemacs} and +Should be highly visible on ＠value{C-E-X} +＠ref{The comp.emacs.xemacs Newsgroup} and ＠value{BETA-LIST} ＠ref{xemacs-beta}. ＠item Release engineer ＠＠ -637,10 +648,12 ＠＠ ＠cindex committer ＠c MH-E says that committers may be _assigned_ bugs -A ＠dfn{committer} is one who is authorized to check in approved changes -into the CVS repository, including changes to private branches they may -maintain. Developers who do not have CVS access contribute by -submitting patches to ＠value{PATCHES-LIST}. +A ＠dfn{committer} is one whose SSH key has been added to the set on the +CVS repository. This gives the necessary access to check in approved +changes into the CVS repository, including changes to private branches +they may maintain. Whether a developers has CVS access or not, their +patches must be submitted to ＠value{PATCHES-LIST} for review, and be +approved, before committing. Commit access is generally given to those who have submitted several good patches, to ``well-known'' developers on request, and to XEmacs ＠＠ -656,8 +669,6 ＠＠ ＠node Commit Access, Committer Welcome Message, Committer, Committer ＠subsection Commit Access -＠c Edited: stephen 2005-01-18 - ＠cindex commit access ＠cindex cvs.xemacs.org committer accounts ＠＠ -674,9 +685,13 ＠＠ ＠c #### fix these urefs!! Developers should be familiar with the -＠uref{http://www.xemacs.org/Documentation/,XEmacs Lisp Manual} +＠uref{http://www.xemacs.org/Documentation/,XEmacs Lisp Manual}, ＠ifinfo -＠xref{Top, XEmacs Lisp Reference, , lispref}. +＠xref{Top, XEmacs Lisp Reference, , lispref}, +＠end ifinfo +＠uref{http://www.xemacs.org/Documentation/,XEmacs Internals Manual} +＠ifinfo +＠xref{Top, XEmacs Internals Reference, , internals}, ＠end ifinfo as well as the ＠uref{http://www.xemacs.org/Documentation/,XEmacs Manual}. ＠＠ -684,8 +699,6 ＠＠ ＠xref{Top, XEmacs User's Guide, , xemacs}. ＠end ifinfo -＠cindex xemacs-design mailing list -＠cindex mailing lists, xemacs-design ＠cindex committer If you think that you may contribute enough to want access to the CVS ＠＠ -962,7 +975,6 ＠＠ ＠node Appointing New Reviewers, Welcoming New Reviewers, XEmacs Reviewer, XEmacs Reviewer ＠subsection Appointing New Reviewers -＠c Created: stephen 2005-01-19 ＠strong{This node needs improvement!!} ＠cindex ＠value{BOARD} ＠＠ -1153,14 +1165,14 ＠＠ ＠cindex meta-maintainer -The ＠dfn{meta-maintainer} is a reviewer who -is responsible for general administration, including recruiting -personnel to handle various chores required to keep the project running -smoothly and handling correspondence for the XEmacs Review Board. The -meta-maintainer generally also fills the role of ``Mr. XEmacs,'' the -public representative of the project. For this reason the -meta-maintainer should be an individual who has earned the respect and -some power in the community, but the role does not provide any +The ＠dfn{meta-maintainer} is a reviewer who is responsible for general +administration, including recruiting personnel to handle various chores +required to keep the project running smoothly and handling +correspondence for the XEmacs Review Board. The meta-maintainer +generally also fills the role of ``Mr. XEmacs,'' the public +representative of the project. For this reason the meta-maintainer +should be an individual who has earned the respect and some personal +power in the community, but the role does ＠emph{not} provide any exceptional power itself. ＠＠ -1200,10 +1212,9 ＠＠ -＠node The Work Flow, XEmacs Resources on the Internet, The Work Roles, Top +＠node The Work Flow, Release Engineering, The Work Roles, Top ＠chapter The Work Flow -＠c Created: stephen 2005-01-20 This section is a description of current best practices, rather than an attempt to define a standard. ＠＠ -1234,7 +1245,8 ＠＠ ＠item Submit the patch. Compose the message so it's easy to find, easy to identify, easy to -review, and easy to apply. +review, and easy to apply. Didier Verna's ＠file{patcher.el} library in +the ＠file{xemacs-devel} package is very useful. ＠item Review the patch. The primary function of the ＠value{BOARD} is to help you improve your ＠＠ -1287,11 +1299,10 ＠＠ ＠value{PROJECT} neither advocates nor discourages this action; it's up to you. -Also, be aware that at the time of writing, January 2005, -Richard Stallman had recently 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. +Also, be aware that in January 2005 Richard Stallman 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. Get more information about procedures from the ＠email{emacs-devel＠(a)gnu.org,GNU Emacs developers' mailing list} or from ＠＠ -1305,9 +1316,6 ＠＠ ＠node Scratching That Itch, Get the Sources, About Copyright Assignment, The Work Flow ＠section Scratching That Itch -＠c Edited: stephen 2005-01-18 -＠c #### needs revision - As always in free software, a patch starts life when some developer somewhere gets an itch. It might be an irritating bug, or someone's report of a bug that bites them; a new feature, whether one's own ＠＠ -1319,7 +1327,8 ＠＠ ＠node Get the Sources, Write Low-Profile Code, Scratching That Itch, The Work Flow ＠section Get the Sources -Maybe he's never worked on XEmacs before. In that case, he'll need to +Maybe our developer has never worked on XEmacs before. In that case, +he'll need to check out the ＠samp{xemacs} module from the CVS repository ＠ref{CVS Repository}. True, he may already have the whole package because he built from source after downloading a tarball. However, tarballs often ＠＠ -1407,7 +1416,6 ＠＠ ＠node Add a ChangeLog Entry, Create the Patch, Test Your Changes, The Work Flow ＠section Add a ChangeLog Entry -＠c Created: stephen 2005-01-21 ＠strong{Needs revision!!} Add a log entry to ＠file{ChangeLog} file in the ancestor directory ＠＠ -1421,8 +1429,6 ＠＠ ＠node ChangeLogs, Log Messages, Add a ChangeLog Entry, Add a ChangeLog Entry ＠subsection ChangeLogs -＠c Edited: stephen 2005-01-18 - ＠strong{This section is pretty close to correct for XEmacs. Needs review.} ＠cindex ChangeLog ＠＠ -1459,7 +1465,7 ＠＠ (install-online): Implemented. (%.info,%.html,%.dvi,%.ps): Added. - *doc/mh-e.texi (Viewing, Showing): Use new keymaps (closes + * doc/mh-e.texi (Viewing, Showing): Use new keymaps (closes SF #621632). ＠end example ＠＠ -1474,22 +1480,21 ＠＠ Multiple targets with the same text may appear in the same entry. -＠cindex Debian - -For consistency, phrase the issue number as follows (＠pxref{Updating -NEWS}): - -＠example - (closes SF #621632). -＠end example - -or - -＠example - (closes Debian #234234). -＠end example +＠c #### we don't have a tracker yet. +＠c For consistency, phrase the issue number as follows (＠pxref{Updating +＠c NEWS}): +＠c +＠c ＠example +＠c (closes SF #621632). +＠c ＠end example + +If there are relevant messages on ＠value{BETA-LIST} or other mailing +lists, you may include one Message-ID, usually the beginning or end of +the thread, in angle brackets as documentation. However, you should +give a brief description of both the issue addressed and the code change +to allow the reader to judge whether he wants to read the thread or not. -The Emacs manual has full documentation on the ＠file{ChangeLog} +The XEmacs manual has full documentation on the ＠file{ChangeLog} commands. When you check in the change log, you do not need to supply any log ＠＠ -1498,8 +1503,6 ＠＠ ＠node Log Messages, , ChangeLogs, Add a ChangeLog Entry ＠subsection Log Messages -＠c Edited: stephen 2005-01-18 - ＠strong{This section, written by Bill Wohler for MH-E and lightly edited to substitute ``XEmacs'' for ``MH-E'', is pretty close to correct for XEmacs, at least in the case of implicit self-approval. Needs review.} ＠＠ -1507,26 +1510,11 ＠＠ ＠cindex log messages ＠cindex ChangeLog -Log messages should be taken from ＠file{ChangeLog}. Given the -＠file{ChangeLog} in the previous section, here is what the log for -＠file{fixhtml} might look like: - -＠example - (dohtml): Now part of main program now that program - only fixes HTML files. Added -w and strict usage. - (usage,dodvi,doinfo): Deleted. - (fix_ref_links): Fixed a few uninitialized variables. Found a - couple of variables and commands that weren't indexed. -＠end example - -Note that the ＠code{*} and the filename have been removed, but this is -not mandatory. However, if the same log message is used for multiple -files, then the associated ＠code{*} and filenames will need to be -present to separate the messages. ＠strong{Is this appropriate for -XEmacs?} - -It is not necessary to add release information since that -information will be encoded in the tags. +One reasonable style for log messages is to take them from +＠file{ChangeLog}. It is not necessary to add release information since +that information will be encoded in the tags. It is a good idea, though +not mandatory, to include the Message-ID of the APPROVE message(s) for +the the patch. At worst, setting the log information will be a cut and paste operation. At best, it will be a keystroke or two. In pcl-cvs, you can ＠＠ -1552,10 +1540,8 ＠＠ ＠node Create the Patch, Submit the Patch, Add a ChangeLog Entry, The Work Flow ＠section Create the Patch -(The following lines describe the current patch creation standard for -developers without commit access, committers, and reviewers alike. An -optional alternative procedure for ＠emph{reviewers only} is likely to be -adopted in first quarter 2005.) +(The following lines describe the patch creation standard for developers +without commit access, committers, and reviewers alike.) Patches should be created using a standard diff(1) such as provided by GNU diffutils, or implemented by CVS. A patch should be a ＠＠ -1575,7 +1561,7 ＠＠ ＠emph{every} patch, context conflicts are extremely likely. On the contrary, since ＠file{ChangeLog} entries are essentially independent of each other, a ＠emph{contextless} ＠samp{diff -U 0} format patch at line -1, or plain text that can be easily cut and pasted, is the preferred +0, or plain text that can be easily cut and pasted, is the preferred format for the ＠file{ChangeLog} diff. These should be prepended to the changeset. ＠＠ -1591,10 +1577,8 ＠＠ ＠cindex patch submission ＠cindex submission, patch -(The following lines describe the current patch submission procedure for -developers without commit access, committers, and reviewers alike. An -optional alternative procedure for ＠emph{reviewers only} is likely to be -adopted in first quarter 2005.) +(The following lines describe the patch submission procedure for +developers without commit access, committers, and reviewers alike.) Send the patch by email to ＠value{PATCHES-LIST}. The subject line should indicate the branch or CVS module in square brackets at the ＠＠ -1671,7 +1655,7 ＠＠ self-approval}. ＠strong{This procedure is not yet in effect, and the commit-trigger has -not yet been implemented at the time of writing. (2005-01-20)} +been only partially implemented at the time of writing. (2006-08-12)} ＠＠ -1683,10 +1667,7 ＠＠ (The following lines describe the current patch submission procedure for developers without commit access and committers. Reviewers may -optionally use ``commit-and-review,'' described later. Another optional -alternative procedure for ＠emph{reviewers only} is likely to be adopted -in first quarter 2005. Called ``implicit self-approval,'' it was -described in the previous section.) +optionally use ``commit-and-review,'' described later.) After the patch has been distributed via ＠value{PATCHES-LIST} reviewers and other developers should review and test the patch. Discussion ＠＠ -1729,7 +1710,7 ＠＠ In cases of the first three actions, the future path of the patch is clear. In the case of a ＠samp{VETO}, the veto may be overridden by three votes for ＠samp{APPROVE} among the reviewers. (It's not clear -to me whether an override requires a majority, including at least three +whether an override requires a majority, including at least three approvals, or a supermajority of two more approvals than vetos.) ＠＠ -1785,7 +1766,7 ＠＠ is no way to supply a message ID reference; that requirement is nullified. ＠strong{This procedure is not yet in effect, and the commit-trigger has -not yet been implemented at the time of writing. (2005-01-20)} +not yet been implemented at the time of writing. (2006-08-12)} ＠＠ -1798,1391 +1779,1251 ＠＠ ＠cindex check-ins, protesting ＠cindex dispute resolution -＠strong{This is a first hack draft by ＠samp{stephen}. I have no idea -whether it represents my own ``true'' opinion, let alone anyone else's.} - -There seems to be general agreement that ＠value{PROJECT} resources -should be used to serve ``the users' needs'' first, before being used -for developers' play---but there is disagreement over who those users -are, and what their needs might be. - -There is general agreement that one of the advantages to working on -XEmacs is the overall coherence of most of its architecture, and the -dedication of the team to refactoring broken designs. However, the -developers with fewer resources to devote feel overwhelmed by the ``code -churn'' generated by the most prolific developers, and protest that -memorizing global renamings and the like are rather frivolous ways to -spend reviewer resources. - -These conflicts typically manifest as a dispute over some reviewer's use -of a veto. Therefore I propose the following guidelines for use of -vetos. - -＠table ＠emph -＠item Only patches can be reviewed. - -And therefore, only patches can be vetoed. People can propose, purely -for discussion, whatever they like. Such proposals ＠strong{may not} be -vetoed. If somebody wants to submit a patch that's clearly against the -sense of some member of the board, let them. It will be vetoed. If -they resubmit a real revision, the reviewers must be allowed to consider -it. - -Note how this deals with the ``use the ISO standard ＠samp{size_t} type -for positive variables'' kind of issue. There's essentially only one -way to write that patch. If it is vetoed and an attempt to override -fails, the policy of the ＠value{BOARD} is clear. The patch should not -be resubmitted until there's good reason to suppose the average stance -of the board has shifted considerably. - -＠item Reviewer decisions apply to the whole patch. - -Including vetos. This makes megapatches risky, obviously. It's up -to the contributor to separate the parts; if something unacceptable is -submitted as part of the megapatch, the reviewer should not be -pressured to accept the whole, nor to do the surgery himself. If the -megapatch is that important to the project, the board should be willing -to override the veto. If the contributor can't get that support, he -must split out the acceptable parts. - -＠item Reasonable time constraints for reviewers. - -Except for global substitutions, megapatches are normally the result of -weeks, even months, of secret work; reviewers should be allowed -proportionate amounts of time to review them. If the work is done -serially via commit-and-review, or on a branch, or (with approval of the -Board) in ＠samp{#ifdef}s, then the reviewers get just as much time as -the originator does, and they have no excuse for being ``surprised'' by -the megamerge at the end. - -Note that the point of a branch here is ＠emph{not} incremental merging, -it is to make progress on the megapatch public. So this costs only the -trivial effort of committing your workspace to the branch every week or -two. (Of course the big merge at the end will still be a lot of work, -but that would be true if all the work was done in a local workspace and -never committed to a branch.) - -＠item Each resubmission of a patch restarts the clock. - -Reviewers need not work faster just because somebody has resubmitted the -patch three times. If you submit a large patch with 52 major bugs, you -had better be prepared to wait a year as it gets vetoed once a week, -once for each bug. - -＠item The submitter must revert an immediate commit if vetoed. - -If you take advantage of implicit self-approval, you have no arguments -because you've short-circuited the review process. Had the patch gone -through the full process, it never would have been applied---you're way -ahead of the game as it is. Revert the patch. - -If the veto is abusive, the abusive reviewer should be disciplined---but -showing that will take discussion, and that must happen after reversion. - -＠item A veto after commit of a fully reviewed patch must be supported. - -If a patch goes through the full submit---review---approve---commit -cycle, it may still be vetoed. However, in this case the burden of -proof should be on the vetoer. The committer ＠emph{may} refuse to -revert, and in that case, the vetoer needs two concurring vetos. This -constitutes a blocking coalition of three---the patch must be reverted -immediately, even if it seems likely that a vote of the board would back -the commit. The patch can be reapplied after the vote. - -Some patches, ie, not submitted by reviewers, need the full -submit---review---approve---commit process in any case. So if reviewers -want some assurance that their patch won't be reverted after commit, -they can take advantage of full review process (which still allows -self-approval). -＠end table +There is no formal dispute resolution procedure. -＠node XEmacs Resources on the Internet, Support Requests, The Work Flow, Top -＠chapter XEmacs Resources on the Internet +＠node Release Engineering, XEmacs Resources on the Internet, The Work Flow, Top +＠chapter Release Engineering -＠c Edited: stephen 2005-01-18 -＠strong{Write this node! Get mailing list and newsgroup information -from the ＠uref{http://www.xemacs.org/Lists/, mailing list page}, -available as the module ＠emph{xemacsweb} ＠ref{CVS Repository}. +＠strong{This node and all of its children need to be reviewed and +adapted to the XEmacs process. One topic that ＠emph{must} be addressed +is regenerating and checking in generated files.} -There should also be a node for the Emacs Wiki.} +＠cindex Release Engineering -＠cindex XEmacs Resources on the Internet +This section contains information about how the XEmacs Project releases +its products. The XEmacs Project is basically an open-access +bazaar-style organization, so it's reasonable to think of the CVS +repository as its primary product. There is no particular ``process'' +for releasing it, it's just there, continuously growing and improving. +The XEmacs Review Board tries to ensure that the CVS HEAD will build +``most of the time'' (at least, for anybody who has successfully +recently built XEmacs). Obviously, however, this can't be guaranteed. + +Note: since the website is automatically regenerated when changes are +committed to its CVS module, even it may be considered to ``live'' in +the CVS repository. + +Some developers have argued that there is no need to go beyond the CVS +repository to a formal release process. This position has some merit, +of course. However, many users and redistributors want and expect some +quality assurance. In order to satisfy this demand, XEmacs has three +independent release series, one for the ＠emph{stable} branch of the core +＠samp{xemacs} module, one for the ＠emph{development} mainline of the +core ＠samp{xemacs} module, and one for the ＠samp{packages} module (which +is currently intended to be ＠emph{stable} at all times). + +This chapter is not a specification mandated by XEmacs Project policy. +Rather, it is a description of ＠dfn{best current practices}, as +understood by Stephen Turnbull. Release policy is determined by the +release engineers. Currently (March 2005) the position of Beta Release +Engineer is open, the Stable Release Engineer is Vin Shelton, and the +Package Release Engineer is Norbert Koch. All of the release engineers +since Steve Baur (1996--1998), as well as a number of other developers +who are involved in publishing XEmacs products, make their tools +available in the ＠samp{xemacs-builds} module of the CVS repository, in +directories named after their common ＠value{XEMACSORG} email nickname. +＠ref{CVS Repository}. These tools can be considered reference +implementations of the release process. + +The next section, Release Schedule, will describe all three +distributions. The remainder will refer specifically to the core +distributions, as content and quality control of packages is generally +the responsibility of the upstream maintainers. The final section will +describe a few tasks that are specific to the package release. ＠menu -* Project Website:: -* CVS Repository:: -* comp.emacs.xemacs:: -* xemacs-beta:: -* xemacs-design:: -* xemacs-patches:: -* xemacs-mule:: -* xemacs-winnt:: +* Release Schedule:: +* Release Prerequisites:: +* Updating NEWS:: +* Updating Version Number:: +* Updating ChangeLogs:: +* Tagging Releases:: +* Creating Tarballs:: +* Creating ＠value{XEMACSORG} Releases:: +* Announce the Release:: +* Updating the Online Documentation:: +* Updating the Free Software Directories:: +* After the Release:: ＠end menu +＠node Release Schedule, Release Prerequisites, Release Engineering, Release Engineering +＠section Release Schedule +This manual does not describe a formal release schedule. However, a +major or minor release which certifies the new features in development +code base stable as a whole should be expected to take six months or +more from the time the proposal is made. + +``Micro'' or ``patchlevel'' releases take place at irregular intervals +at the discretion of the responsible release engineer. It seems +desirable for micro releases from the mainline to occur at biweekly to +monthly intervals, based on either integration of new features that need +intensive testing, or appearance of a relatively stable code base that +can be used as a baseline for testers to fall back to in the event of +destabilizing changes. In practice beta releases seem to occur much +less frequently, sometimes as far as six months apart. + +Micro releases from the stable branch should take place after +a fix for a critical bug is integrated, or after two to four months +accumulation of minor fixes and documentation improvements. This rate +is consistent with what has been observed over the 21.1 and 21.4 stable +branches. + +The packages have a different structure. The current practice is to +create a release candidate and announce it as a ``pre-release'' +immediately after patches to an individual package, then promote it to +the main package distribution after two to four weeks with no problems. +Several years' experience have shown that this pattern serves the users +very well. SUMO tarballs are generally released two to four times +annually, often after a fix to an infrastructure package such as EFS. +This system has worked extremely well. -＠node Project Website, CVS Repository, XEmacs Resources on the Internet, XEmacs Resources on the Internet -＠section Project Website -＠c Edited: stephen 2005-01-18 -＠strong{Needs review. Adrian?} +＠node Release Prerequisites, Updating NEWS, Release Schedule, Release Engineering +＠section Release Prerequisites -＠cindex Project Website -＠cindex ＠value{XEMACSORG}, XEmacs Web space +Before XEmacs can be released, that is, the CVS repository tagged and +tarballs created and uploaded, a number of prerequisites must be +satisfied. + +＠table ＠strong +＠item The NEWS file must be updated + +On the stable branch this file is called ＠file{NEWS}. On other +branches, it's named ＠file{CHANGES-＠var{branch}} (for the mainline, +＠file{CHANGES-beta}). + +＠item Version references must be verified and updated + +Specifically, the version in ＠file{version.sh} ＠emph{must} be correct or +the release will be invalid, and several engineers' scripts try to +enforce correct versioning in ＠file{CHANGES}. + +＠item Generated source files must be regenerated + +Currently the ＠dfn{generated source} files are ＠file{configure}, +＠file{src/depend}, ＠file{src/intl-auto-encap-win32.h}, and +(a)file{src/intl-auto-encap-win32.h}. Update ＠file{configure} by running +＠file{autoconf} in the root of the source tree, ＠file{src/depend} by +running ＠code{make depend} in ＠file{src}, and +(a)file{intl-auto-encap-win32.*} by running +＠code{make unicode-encapsulate} in ＠file{src}. + +``Generated source'' may seem like an oxymoron, but it's not. Files +like ＠file{configure} are intended to be portable. If ＠file{configure} +were not in CVS and the tarballs, users wishing to install XEmacs would +need to install and keep up to date ＠file{autoconf} and its libraries, and +GNU ＠file{m4}. The other generated files require ＠file{perl}. + +＠item The release candidate must build, and pass the test suite + +For a beta release, the candidate code base must build on at least the +engineer's platform since the LISP files must be compiled. If the build +does not pass ＠code{make check}, all such failures must be noted in the +release announcement. The beta release engineer is encouraged to +subject the code base to the more rigorous tests required of the stable +branch, but it's up to his judgement whether to postpone the release in +case of failures. + +A stable release candidate must build on all platforms available to +release engineer personally, as well as on any platforms used by beta +testers. The candidate should be tested under several configurations. +In particular, it should be tested with and without Mule, with TTY +support only, with Athena, Motif, and GTK support, with and without +dialogs and widgets, and with and without the union implementation of +＠samp{Lisp_Object}. The regression tests must be passed 100% in each +case. ＠emph{(At the discretion of the release engineer, an exception +may be made for failures that occur because a new test for an as-yet +unresolved defect has been added. Unpleasant, but often necessary.)} -The ＠uref{http://www.xemacs.org/, XEmacs home page} contains a brief -overview of the XEmacs project. This Web space also includes other -internal documents, such as this one. +＠end table -＠c #### this probably belongs elsewhere? this subtree is more user-oriented. -To install your updates into the XEmacs Web space at ＠value{XEMACSORG}, -simply check out the ＠file{xemacsweb} module ＠ref{CVS Repository}, make -your changes, and check it in. The commit script takes care of -generating the HTML and pushing the changes to the web servers' document -spaces. +＠node Updating NEWS, Updating Version Number, Release Prerequisites, Release Engineering +＠section Updating NEWS -＠node CVS Repository, comp.emacs.xemacs, Project Website, XEmacs Resources on the Internet -＠section CVS Repository +＠cindex NEWS +＠cindex news -＠c Edited: stephen 2005-01-18 +The NEWS file must be updated at each release. This file announces +user- and programmer-visible changes. It should not include +implementation details. In the stable branch, the NEWS file is actually +called ＠file{NEWS}, while in the mainline it is called +＠file{CHANGES-beta}. Other branches often have their own +＠file{CHANGES-＠var{branch}}. -＠cindex CVS Repository +In order to discover items appropriate for ＠file{NEWS}, several things +can be done. -＠c #### update the specific links for convenience!! -The ＠uref{http://cvs.xemacs.org/,CVS Repository} -contains several modules. You can view the repository with ViewCVS from -a link on repository's home page, and there is a link to an explanation -of how to use CVS in the CVS Repository. +＠enumerate +＠item +Use the ChangeLog. +＠item +Once a release date has been determined, the milestones leading up to +that release should be posted as news items (＠pxref{News}). -＠node comp.emacs.xemacs, xemacs-beta, CVS Repository, XEmacs Resources on the Internet -＠section The Usenet Newsgroup comp.emacs.xemacs +＠end enumerate -＠strong{Write me!} +The previous steps usually catch most items. To use a finer sieve, use +the following commands. These assume that the last release of XEmacs +package was 21.4.17. +＠example + cvs log -rr21-4-17 + cvs diff -rr21-4-17 +＠end example +See section ＠ref{Updating ChangeLogs} before checking in this file. -＠node xemacs-beta, xemacs-design, comp.emacs.xemacs, XEmacs Resources on the Internet -＠section The xemacs-beta Mailing List -＠strong{Write me!} +＠node Updating Version Number, Updating ChangeLogs, Updating NEWS, Release Engineering +＠section Updating Version Number +XEmacs version information is kept in the file +＠value{VERSIONFILE}. This file must be valid when sourced +by a POSIX shell and when included by a portable Makefile. -＠node xemacs-design, xemacs-patches, xemacs-beta, XEmacs Resources on the Internet -＠section The xemacs-design Mailing List +The first in a series of stable releases is a special case, because it +involves creation of a new stable branch and affects numbering of the +trunk as well. In the new stable branch, ＠value{VERSIONFILE} must +assign the empty value to ＠samp{emacs_is_beta}. The value ``0'' is +assigned to ＠samp{emacs_beta_version}. The next ＠emph{even} number +(which is ``0'' in the case that ＠samp{emacs_major_version} is bumped) +is assigned to ＠samp{emacs_minor_version}, and +＠samp{emacs_major_version} is bumped if that was authorized by the +XEmacs Review Board. The codename ＠samp{xemacs_codename} is assigned at +the discretion of the stable release engineer. -＠strong{Write me!} +At the same time, a new release of the trunk, identical except for +version information, is made. ＠emph{The version information is the same +as the stable release}, except that ＠samp{emacs_is_beta} is set to +＠samp{t}, ＠samp{emacs_minor_version} is bumped to the next ＠emph{odd} +integer, and ＠samp{xemacs_codename} is assigned at the discretion of the +beta release engineer. + +(New in XEmacs 21.5.20) When a release is made, the variable +＠samp{xemacs_release_date} should be set appropriately. This variable +is not used in the build process, but simply imported into LISP, where +it is used in various documentation modules, such as ＠file{about.el}. +Release engineers usually choose a theme for codenames and make the +proposed series available in a file. The name ＠samp{emacs_beta_version} +probably could have been more aptly chosen, but it is a historical relic +of the fact that it was first used in the beta series, then adopted in +the stable branch. The name is not user-visible; the value of this +variable is called the patch level in stable branch documentation. +(a)strong{N.B.} Release engineers should avoid disturbing the order of +variables in ＠value{VERSIONFILE}. The variables +＠samp{emacs_kit_version}, ＠samp{infodock_major_version}, +＠samp{infodock_minor_version}, and ＠samp{infodock_build_version} are +used for version information of various non-＠value{PROJECT} releases, +and should be ignored. Both of these features are unclean, but users' +auxiliary tools (and some tools distributed by the ＠value{PROJECT}, +including ＠file{build.el} and ＠file{build-report.el} in some releases) +often depend on the syntax of this file to work correctly. In beta +releases, there is an optional variable ＠samp{xemacs_extra_name} which +is a string that is appended to the version string. It is currently +automatically updated, and used to identify the date of a CVS checkout. -＠node xemacs-patches, xemacs-mule, xemacs-design, XEmacs Resources on the Internet -＠section The xemacs-patches Mailing List +Except in cases involving creation of a new stable branch, update of the +version information simply requires bumping ＠samp{emacs_beta_version} +(and ＠samp{xemacs_release_date} in XEmacs releases from 21.5.20) and +assignment of a new ＠samp{xemacs_codename}. -＠strong{Write me!} +＠heading Grep the sources +The version number appears in a large number of fairly random places. +The release engineer should grep the whole tree for the pattern +(a)samp{[0-9]+\.[0-9]+\.[0-9]+}, and check each hit. First, check that +the relevant text (which might be limited to a short comment in a source +file, or might be the whole file for a documentation file like +＠file{INSTALL}) is appropriate for the version to be released. Second, +check that the version number found corresponds to the text. Third, +try to regularize references (e.g., to "XEmacs 21.4.17") so that the +grep can be refined in future versions. Fourth, try to substitute +variable or macro references in executable contexts. Fifth, try to +eliminate unnecessary references to versions. -＠node xemacs-mule, xemacs-winnt, xemacs-patches, XEmacs Resources on the Internet -＠section The xemacs-mule Mailing List -＠strong{Write me!} +＠node Updating ChangeLogs, Tagging Releases, Updating Version Number, Release Engineering +＠section Updating ChangeLogs +＠cindex ChangeLog +Add a ChangeLog entry to ＠emph{every} ＠file{ChangeLog} in the tree, +marking the release. The text of the first line should match this +regexp: -＠node xemacs-winnt, , xemacs-mule, XEmacs Resources on the Internet -＠section The xemacs-winnt Mailing List +＠example +XEmacs [0-9]+\(?:\.[0-9]+\)+ \(?:"\(\w\|\s-\)+"\)? is released. +＠end example -＠strong{Write me!} +For example, +＠example +2005-03-12 Stephen J. Turnbull <stephen＠(a)xemacs.org&gt; + * XEmacs 21.5.20 "cilantro" is released. -＠c ########################################################################## -＠c #### I haven't seriously worked on the following material. -- stephen #### -＠c ########################################################################## +＠end example -＠node Support Requests, Bugs, XEmacs Resources on the Internet, Top -＠chapter Support Requests +(Note that the ``21.5-b20'' style used by `emacs-version' in beta +XEmacsen is deprecated.) Normally this should be the ＠emph{only} text +in the ChangeLog entry. -＠cindex Support Requests +＠node Tagging Releases, Creating Tarballs, Updating ChangeLogs, Release Engineering +＠section Tagging Releases -Support requests are made to ＠value{BETA-LIST}. Developers should read -the mailing list frequently, and after a period of inactivity, browse -the ＠uref{http://list-archive.xemacs.org/xemacs-beta/,recent archives}. +＠cindex tags +＠cindex CVS, tag +＠cindex version numbers +It is critical that a snapshot of the software is created each time +the software is released. In CVS, this is performed with tags. +Every series of stable releases must have a branch tag of the form +＠i{release-M-N}. The trunk has no branch tag. Every release must have +a fixed tag of the form ＠i{rM-N-B}, where ＠var{m} is the major +number, ＠var{n} is the minor number, and ＠var{b} is the beta release or +patch number. A hyphen is used since one cannot use dots in CVS tag +names. Note the ＠var{B} is simply a number, not something like +＠samp{b1} or ＠samp{pre2} as used in the past. -＠node Bugs, Feature Requests, Support Requests, Top -＠chapter Bugs +＠c #### is it *-current-beta or *-latest-beta?? +The stable release branch tag doubles as a tag of the most recent +release. While this is not quite true during the process of +accumulating patches to the branch, due to the conservative nature of +that process it seems very unlikely to cause trouble. Since the trunk +has no tag, and many beta testers would prefer to avoid checking out in +the middle of a series of related check-ins, a fixed tag of the form +＠i{release-M-N-current-beta} is used to identify the current beta +release. It is updated by a command like ＠samp{cvs tag -F -r +release-M-N-B release-M-N-current-beta}. (N.B. It would be preferable +to use the rtag command, since that tags ＠emph{all} files, living and +dead. However, due to bugs in CVS and the current file hierarchy on our +CVS host, ＠samp{cvs rtag} does not work.) -＠c Edited: stephen 2005-01-18 +The packages have independent release schedules, determined by each +XEmacs package maintainer and the XEmacs Package Release Engineer. -＠strong{We don't have a tracker. We should. Describe what it should -look like here.} -＠cindex Bugs -＠cindex priority -＠cindex bugs, priority +＠node Creating Tarballs, Creating ＠value{XEMACSORG} Releases, Tagging Releases, Release Engineering +＠section Creating Tarballs -Bug reports, feature requests, and discussions that are expected to lead -to bug reports or feature requests are created in -＠uref{https://sourceforge.net/bugs/?group_id=13357, Bugs}. Most -bugs should be set to a priority of 5. +＠cindex Creating Tarballs +＠cindex CVS Repository +＠cindex modules +＠cindex CVS, modules +＠cindex tarballs, naming -＠cindex bug-gnu-emacs -＠cindex Debian +Besides the CVS tag, a stable release involves uploading a number of +tarballs to the primary archive at ftp.xemacs.org. -Developers should follow the ＠i{bug-gnu-emacs} mailing lists/newsgroup -and move bug reports into Bugs if it has not been done already. -Similarly, XEmacs bugs reported in other systems should be transfered to -＠value{XEMACSORG}. The bug may be cut and pasted into a new bug report, or a -URL to the source of the original bug report may be all that appears -in the bug report. +＠c The "(b-1)" below will generate a makeinfo warning. Ignore it. +＠c +In the following descriptions, ＠var{version} refers to the release +version number as an ＠samp{＠var{m}.＠var{n}.(a)var{b}} triple. +＠var{previous} refers to the previously released version, most +frequently ＠samp{＠var{m}.＠var{n}.(a)var{(b-1)}}. -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. +＠table ＠strong -The assignment of bugs in Bugs follows the honor system. If you see an -open bug that you think you could handle, assign the bug to yourself. -Bugs that remain open should be reviewed by a member of the -＠value{BOARD}, who should try to find a developer to work on the bug. +＠item full release +＠file{xemacs-(a)var{version}.tar.gz} -If you fix a bug, set the resolution to Fixed and group to CVS. Please -also assign the bug to yourself if you have not done so already, so -you get credit in the -＠uref{https://sourceforge.net/tracker/reporting/?atid=113357&what=tech&span=&period=lifespan&group_id=13357#b, -reports}. If a documentation change is not required, set the status to -Closed. If a documentation change is required, set the category to -Documentation, and assign the bug to the documentation tsar, -leave the status Open, and set the priority to 3 to set it -aside in listings sorted by priority. +The full release, containing all architecture-independent generated +files. Equivalent to the combinarion of the source-only, compiled LISP, +and prebuilt Info tarballs. -See ＠ref{File Releases} for a motivation of why this process is useful. +＠item source-only +＠file{xemacs-(a)var{version}-src.tar.gz} -The rest of this section describes the categories and groups that have -been set up for the XEmacs project. +Contains only the pristine sources. -＠menu -* Category:: -* Status:: -* Group:: -* Resolution:: -＠end menu +＠item compiled LISP +＠file{xemacs-(a)var{version}-elc.tar.gz} -＠node Category, Status, Bugs, Bugs -＠section Category +Contains the compiled LISP (＠file{.elc}) files, ready to install. -＠cindex category -＠cindex bug category +＠item prebuilt Info +＠file{xemacs-(a)var{version}-info.tar.gz} -Several categories have been created for the XEmacs project organized by -function. They include ＠i{General}, ＠i{UI}, ＠i{MIME}, ＠i{Security}, -＠i{Documentation}, and ＠i{Contrib} +Contains the Info (＠file{.info}) files, compiled from ＠file{.texi} and +ready to install. -＠table ＠b +＠item changeset +＠file{xemacs-＠var{version}-(a)var{previous}.patch.gz} -＠item General +Contains a changeset, built by the ＠file{makepatch} utility. This is a +multipurpose file. It can be run as a shell script, or applied via the +＠file{applypatch} utility. These utilities provide some features not +available in ＠file{patch} such as file renaming. Alternatively, you +may apply it with ＠file{patch} as an ordinary diff, but in rare cases +this may fail to implement file additions, deletions, and renamings. -＠cindex general bug category -＠cindex bug categories, general +＠end table -The ＠dfn{General} category is used for bugs that do not belong in any of -the other categories. +Beta releases generally provide only the full release tarball and the +changeset. -＠item UI +＠cindex tarballs, making +＠cindex tarballs, naming +＠cindex tags +＠cindex CVS, tags +＠cindex Makefile targets, dist +＠cindex version numbers -＠cindex UI bug category -＠cindex bug categories, UI +The general procedure for making a set of tarballs is -The ＠dfn{UI} category is used for bugs in the software that the user sees -such as font-lock, key definitions, menus, and customization. +＠enumerate +＠item +Check out the current version and the previous version. -＠item MIME +＠item +Use ＠file{makepatch} to create a ＠strong{changeset} file, then compress +it with ＠file{gzip}. Run ＠file{makepatch} from the directory that is +the parent of the checked-out trees. -＠cindex MIME bug category -＠cindex bug categories, MIME +＠item +Use ＠file{tar} and ＠file{gzip} to create the ＠strong{source-only} +tarball. The tarball should include the root directory of the source +tree, which should be named ＠file{xemacs-＠var{version}}. -The ＠dfn{MIME} category is used for bugs that pertain to MIME. - -＠item Security - -＠cindex security bug category -＠cindex bug categories, security - -The ＠dfn{Security} category is used for bugs in the security arena. At -present, XEmacs does not include any security code, so this category might -be used for PGP interaction. - -＠item Documentation - -＠cindex documentation bug category -＠cindex bug categories, documentation - -The ＠dfn{Documentation} category is used for bugs in the documentation -arena. In addition, if there are any code changes made as a result of a -bug report or feature request that require changes to the documentation, -the category of that issue should be set to Documentation after the bug -has been fixed or the feature implemented. Assign the issue to -＠i{wohler} for editing and/or writing of the documentation, and set -the priority to 3 to set the issue aside in listings sorted by priority. - -＠item Contrib - -＠cindex contrib bug category -＠cindex bug categories, contrib - -The ＠dfn{Contrib} category is used for all bugs in the contributed -software. - -＠end table +＠item +Build the release, configuring ＠samp{--with-mule} (in releases 21.5.20 +and later, this option has been renamed ＠samp{--enable-mule} to conform +to Autoconf 2.5x conventions). The build must be done with Mule, as a +no-Mule XEmacs will not (and cannot) compile the Mule LISP files. -＠node Status, Group, Category, Bugs -＠section Status +＠item +Use ＠file{tar} and ＠file{gzip} to create the ＠strong{full release}, +＠strong{compiled LISP}, and ＠strong{prebuilt Info} tarballs. The +tarball should include the root directory of the source tree, which +should be named ＠file{xemacs-＠var{version}}. The ＠strong{compiled LISP} +and ＠strong{prebuilt Info} tarballs need include only the +＠file{xemacs-＠var{version}/lisp} and ＠file{xemacs-＠var{version}/info} +subtrees, respectively. -＠cindex status -＠cindex bug status +＠item +PGP sign all products. +＠end enumerate -The bug ＠dfn{status} is divided into four sections: ＠i{Open}, -＠i{Closed}, ＠i{Deleted} and ＠i{Pending}. +For more details, see the release scripts used by Steve Youngs, Vin +Shelton, Stephen Turnbull, and Martin Buchholz in the ＠file{youngs}, +＠file{acs}, ＠file{stephen}, and ＠file{martin} subdirectories of the +＠file{xemacs-builds} CVS module. When in doubt, Martin's scripts should +be considered canonical. -＠table ＠b -＠item Open -＠cindex open bug status -＠cindex bug status, open +＠node Creating ＠value{XEMACSORG} Releases, Announce the Release, Creating Tarballs, Release Engineering +＠section Creating ＠value{XEMACSORG} Releases -When bugs are initially created, they are marked ＠dfn{Open}. +＠cindex Creating ＠value{XEMACSORG} Releases +＠cindex releases +＠cindex tarballs, making -＠cindex discussing bugs -＠cindex bugs, discussing -＠cindex features, discussing +＠enumerate +＠item +Create the tarballs, changeset, and PGP signatures +(＠pxref{Creating Tarballs}). -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. +＠item +Upload the tarballs, changeset, and PGP signatures to a temporary +subdirectory of the release directory on ftp.xemacs.org. (You will need +an account on tux.org, our host.) For the mainline, the release +directory is ＠file{ftp://ftp.xemacs.org/pub/xemacs/beta}, and for the +stable branch, it is ＠file{ftp://ftp.xemacs.org/pub/xemacs/stable}. -Discussion about entirely new features should be opened in the Feature -Requests section (＠pxref{Feature Requests}) but otherwise handled in -the same way. +＠item +Check the PGP signatures. -＠item Closed +＠item +Move the products into the release directory. -＠cindex closed bug status -＠cindex bug status, closed +＠item +Remove any existing ``LATEST IS'' files, and touch +＠file{LATEST-IS-＠var{version}} and ＠file{LATEST.IS.＠var{version}}. -When all aspects of a bug have been fixed, including code and -documentation, the bug is marked ＠dfn{Closed}. +＠item +Update the files ＠file{README} and ＠file{.message} in +＠file{ftp://ftp.xemacs.org/pub/xemacs}. +＠end enumerate -When setting the status to Closed, the group should be set to Fixed, -Works For Me, Invalid, or Rejected. -＠item Pending -＠cindex pending bug status -＠cindex bug status, pending +＠node Announce the Release, Updating the Online Documentation, Creating ＠value{XEMACSORG} Releases, Release Engineering +＠section Announce the Release -You can set the status to ＠dfn{Pending} if you are waiting for a -response from the tracker item author. When the author responds, the -status is automatically reset to that of Open. Otherwise, if the -author doesn't respond within 14 days, then the item is given a status -of Deleted. +＠cindex Announce the Release -＠item Deleted +Now that the release is ready for download, announce it as described +in ＠xref{News}. -＠cindex deleted bug status -＠cindex bug status, deleted +＠node Updating the Online Documentation, Updating the Free Software Directories, Announce the Release, Release Engineering +＠section Updating the Online Documentation -If an items has been marked Pending, it will be marked ＠dfn{Deleted} -if the author of the item does not respond within 14 days. +＠strong{Adrian, please review.} -＠end table +＠cindex Updating the Online Documentation +＠cindex online documentation, updating +＠cindex documentation, updating online +＠cindex CVS, update -＠node Group, Resolution, Status, Bugs -＠section Group +The entire XEmacs web site is kept in CVS, and automatically rebuilt by +the commit trigger. -＠cindex group -＠cindex bug group +Thus, the basic procedure is similar to working on XEmacs source code. -The bug ＠dfn{group} contains several items. They include: +＠enumerate +＠item +Check out the ＠samp{xemacsweb} module. -＠table ＠b +＠item +Make the needed changes. -＠item None +＠item +Update the ChangeLog(s). -Bugs are initially filed in this group. +＠item +Test the changes with ＠code{make} to ensure that all ＠file{genpage} +commands are correct. Then use ＠code{make validate} to check that the +produced HTML is reasonably correct. -＠item CVS* +＠item +Commit the workspace. +＠end enumerate -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. +The XEmacs online documentation is mostly written in the ＠file{genpage} +language, which ensures a consistent interface for internal links via +special commands processed by the ＠code{genpage} script, and a +consistent overall format enforced by use of template files. Some of +the material, such as the online versions of the ＠emph{XEmacs User's +Guide} is generated directly from Texinfo, and checked in to CVS as HTML +rather than ＠file{genpage} source. -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. +The validator used by ＠code{make validate} is based on the PSGML +package. It is not perfect, but it is more convenient than the more +accurate online validators provided by the W3C and others. The +webmaster should use the online validators and link checkers regularly. -＠item mh-e* -Bugs in groups starting with mh-e have either been found in the given -version if the Status is Open, or fixed in the given version if the -Status is Closed. -＠end table +＠node Updating the Free Software Directories, After the Release, Updating the Online Documentation, Release Engineering +＠section Updating the Free Software Directories -＠node Resolution, , Group, Bugs -＠section Resolution +＠strong{Add FreshMeat, at least.} -A bug can appear in various states: +Update the ＠i{source-tarball} and ＠i{version} fields in the FSF/UNESCO +Free Software Directory (＠pxref{Free Software Directories}), as well as +the ＠i{touched} field. Update any other fields as necessary, including +the ＠i{updated} field. -＠table ＠b +＠node After the Release, , Updating the Free Software Directories, Release Engineering +＠section After the Release -＠item Accepted +＠cindex After the Release -＠cindex accepted resolution -＠cindex resolution, accepted +Get ready for the next one! -The ＠dfn{Accepted} resolution means that QA has accepted the fix. -Since we don't have a QA department, it is unlikely that this will be -used in that fashion. Instead, it can be used to indicate that a -developer feels that a feature request (that someone else posted) has -merit. -＠item Duplicate -＠cindex duplicate resolution -＠cindex resolution, duplicate +＠node XEmacs Resources on the Internet, Support Requests, Release Engineering, Top +＠chapter XEmacs Resources on the Internet -The ＠dfn{Duplicate} resolution means that this bug is a duplicate of -another. The status may be set to Closed. Be sure to add a note which -mentions the bug number that this bug is a duplicate of. If this bug -has some good information in it, the URL to this bug should be added -to the duplicate. +＠strong{Write this node! Get mailing list and newsgroup information +from the ＠uref{http://www.xemacs.org/Lists/, mailing list page}, +available as the module ＠emph{xemacsweb} ＠ref{CVS Repository}. -＠item Fixed +There should also be a node for the Emacs Wiki.} -＠cindex fixed resolution -＠cindex resolution, fixed +＠cindex XEmacs Resources on the Internet -The ＠dfn{Fixed} group is used to indicate a bug or feature request that -has been fixed. +＠menu +* The xemacs.org Domain:: +* Project Website:: +* CVS Repository:: +* The comp.emacs.xemacs Newsgroup:: +* XEmacs Mailing Lists:: +＠end menu -＠item Invalid -＠cindex not a bug resolution -＠cindex invalid resolution -＠cindex resolution, not a bug -＠cindex resolution, invalid -The ＠dfn{Invalid} resolution is used to indicate the problem is with -the user. In other words, this is not a bug. See Works For Me. +＠node The xemacs.org Domain, Project Website, XEmacs Resources on the Internet, XEmacs Resources on the Internet +＠section -＠item Later +The xemacs.org domain is registered to Sandy Wambold, <sandy＠(a)xemacs.org&gt;. -＠cindex later resolution -＠cindex resolution, later +The domain management services (DNS and MX) are provided by Tux.org. +The configurations are maintained by XEmacs, and installed via +＠file{sudo}. -The ＠dfn{Later} resolution is similar to the Postponed group, although -it connotates a longer delay. -＠item Out of Date -＠cindex out of date resolution -＠cindex resolution, out of date -The ＠dfn{Out of Date} resolution is similar to the term OBE (Overcome -By Events). In other words, the bug has not been fixed, but the code -has changed in ways that make it unnecessary to do so. +＠node Project Website, CVS Repository, The xemacs.org Domain, XEmacs Resources on the Internet +＠section Project Website -＠item Postponed +＠strong{Needs review. Adrian?} -＠cindex postponed resolution -＠cindex resolution, postponed +＠cindex Project Website +＠cindex ＠value{XEMACSORG}, XEmacs Web space -The ＠dfn{Postponed} resolution is similar to the Later group, although -it connotates a lesser delay. +The ＠uref{http://www.xemacs.org/, XEmacs home page} contains a brief +overview of the XEmacs project. This Web space also includes other +internal documents, such as this one. -＠item Rejected +＠c #### this probably belongs elsewhere? this subtree is more user-oriented. +To install your updates into the XEmacs Web space at ＠value{XEMACSORG}, +simply check out the ＠file{xemacsweb} module ＠ref{CVS Repository}, make +your changes, and check it in. The commit script takes care of +generating the HTML and pushing the changes to the web servers' document +spaces. -＠cindex rejected resolution -＠cindex resolution, rejected -The ＠dfn{Rejected} resolution means that QA has rejected the fix. -Since we don't have a QA department, it is unlikely that this will be -used in that fashion. Instead, it can be used to indicate that a -developer feels that a feature request does not have merit. -＠item Remind +＠node CVS Repository, The comp.emacs.xemacs Newsgroup, Project Website, XEmacs Resources on the Internet +＠section CVS Repository -＠cindex remind resolution -＠cindex resolution, remind +＠cindex CVS Repository -The ＠dfn{Remind} resolution is similar to the Postponed and Later -groups, although it connotates an even lesser delay. +＠c #### update the specific links for convenience!! +The ＠uref{http://cvs.xemacs.org/,CVS Repository} +contains several modules. You can view the repository with ViewCVS from +a link on repository's home page, and there is a link to an explanation +of how to use CVS in the CVS Repository. The repository is hosted by +SunSITE.dk. -＠item Wont Fix +＠strong{Somebody, write me! We especially need cvsaccess.html and a +description of each module here.} -＠cindex wont fix resolution -＠cindex resolution, wont fix -The ＠dfn{Wont Fix} resolution means that the XEmacs developers -acknowledge that the bug exists but are not going to fix it. Or the -developers will not implement a feature request. There is probably a -good reason for these things. -＠item Works For Me +＠node The comp.emacs.xemacs Newsgroup, XEmacs Mailing Lists, CVS Repository, XEmacs Resources on the Internet +＠section The Usenet Newsgroup comp.emacs.xemacs -＠cindex irreproducible resolution -＠cindex resolution, irreproducible -＠cindex works for me resolution -＠cindex resolution, works for me +＠strong{Somebody, write me!} -The ＠dfn{Works For Me} group is used to indicate a bug that cannot be -reproduced (irreproducible) and therefore cannot be fixed. See -Invalid. -＠end table -＠node Feature Requests, Patch Queue, Bugs, Top -＠chapter Feature Requests +＠node XEmacs Mailing Lists, , The comp.emacs.xemacs Newsgroup, XEmacs Resources on the Internet +＠section XEmacs Mailing Lists -＠c Edited: stephen 2005-01-18 +The XEmacs mailing lists are managed using the Mailman list management +package, archived and indexed with MHonArc, spam-filtered with procmail, +SpamAssassin, and locally-developed Mailman Handlers, and hosted on +Tux.org's hardware and Internet connection. -＠cindex Feature Requests +＠menu +* Maintaining the Mailing Lists:: +* xemacs-announce:: +* xemacs-beta:: +* xemacs-cvs:: +* xemacs-buildreports:: +* xemacs-design:: +* xemacs-mule:: +* xemacs-patches:: +* xemacs-review:: +* xemacs-winnt:: +＠end menu -Developers should check the -＠uref{https://sourceforge.net/patch/?group_id=13357, Feature Requests} -occasionally for new feature requests and comment on the feature's -usefulness and integrity. Unless a positive comment has -＠c #### define "reasonable" -been added within a ``reasonable'' amount of time, a member of the -＠value{BOARD} -may set the status to Closed and the group to Wont Fix. ＠value{BOARD} -members should regularly check the list of requested features and prune -the oldest in this way to keep the list to a reasonable size. -＠c mh-e-devguide sez: -＠c will set the status to Closed and the group to Wont Fix. If the -＠c feature request is not closed, anyone may assign the request to -＠c themselves and implement the feature. -After incorporating the feature, update the feature request as -described in the previous section (＠pxref{Bugs}). -＠node Patch Queue, File Releases, Feature Requests, Top -＠chapter Patch Queue +＠node Maintaining the Mailing Lists, xemacs-announce, XEmacs Mailing Lists, XEmacs Mailing Lists +＠subsection Maintaining the Mailing Lists -＠c Edited: stephen 2005-01-18 +The XEmacs mailing lists are managed with GNU Mailman, procmail, +SpamAssassin, and MHonArc. -＠cindex Patch Queue +＠heading The Life-Cycle of a Post -Developers should check ＠value{PATCHES-LIST} -occasionally for new patches and comment on the patch's usefulness and -integrity. This will greatly help reviewers to review patches. Note -that developers who are active in commenting on patches and bug reports -are the main candidates when recruiting new reviewers. +The following discussion presumes a fair familiarity with the software +used, both in general (MTAs, MLMs, etc) and the specific software used +by XEmacs (sendmail, procmail, GNU Mailman, etc.) -＠c Legally speaking, patches that are less than 15 lines can usually be -＠c incorporated, although it is always best to try to incorporate them in -＠c a ``clean room'' environment. Do read -＠c ＠uref{http://www.gnu.org/prep/maintain_6.html#SEC6, Legally -＠c Significant Changes} for the details. +Let's follow a post to XEmacs Beta (which gets the heaviest traffic of +XEmacs mailing lists). It originates at some user's MUA, gets processed +by their MTA, which gets our MX from the DNS. The post is delivered to +＠file{sendmail} on mail.xemacs.org (actually, gwyn.tux.org in drag), +which passes it through a greylisting milter, checks for some RBLs, and +a milter for ClamAV. +Then it sends the post to an alias for ＠code{xemacweb＠(a)xemacs.org}, +which uses ＠file{formail} to tag the post with a private header naming +the destination list, then passes the post through ＠file{procmail}. +＠file{procmail} in turn passes the post to ＠file{spamc} for filtering, +then checks SpamAssassin's report, as well as a large number of +hardcoded recipes for spam. If the post survives these checks, procmail +forwards it to Mailman. Most spam is simply dropped on the floor, but a +significant amount (several score posts per day) is diverted (see the +section on ``Handling Spam'' below). +Mailman passes the post through a variant of its standard pipeline, +including a couple of XEmacs-specific Handlers. The +(a)file{XEmacsSource.py} handler checks for spam that attempts to +short-circuit the pipeline. The ＠file{XEmacsArchiver.py} handler +archives the post by piping it to a Perl script originally from +majordomo called ＠file{archive2-y2k.pl} in +＠file{/opt/archives/majordomo} (if I recall correctly). +＠c #### CHECK!! +The archives themselves are simply mbox files in +＠file{/opt/archives/majordomo/xemacs}. +＠c #### CHECK!! -＠node File Releases, News, Patch Queue, Top -＠chapter File Releases +The web archive and indices are automatically generated by a cron job +that runs ＠file{MHonArc} and ＠file{glimpseindex} once per day. The +archives live in ＠file{/httpd/xemacs/list-archive}. +＠c #### CHECK!! +The MHonArc and glimpse configuration files are dotfiles in the archive +directories. +＠c #### CHECK!! -＠c Edited: stephen 2005-01-18 +XEmacs MXes are provided by mail.xemacs.org and extundo.org, courtesy of +Simon Josefsson. -＠strong{This node and all of its children need to be reviewed and -adapted to the XEmacs process. One topic that ＠emph{must} be addressed -is regenerating and checking in generated files.} +Most of the software is maintained by Tux.org. Specifically, Tux +provides up-to-date versions ＠file{sendmail} and its milters, +＠file{procmail} and its subsidiary utilities (particularly +＠file{formail}), ＠file{spamassassin}, ＠file{spamd}, and ＠file{spamc} +(the SpamAssassin suite is way out of date as of 2006/08/12), GNU +Mailman, MHonArc, the glimpse suite, ＠file{named} (BIND 9), and the +Apache ＠file{httpd}, as well as ＠file{perl} and ＠file{python}. Problems +with any of these must be resolved by Tux personnel, who can be reached +at the ＠email{administrators＠(a)tux.org, Tux Administrators} mailing list. -＠cindex File Releases +XEmacs provides and maintains ＠file{archive-y2k.pl}, ＠file{namazu} (an +indexing system, not currently implemented for the list archives), and +＠file{xemacs} itself. The xemacs.org virtual host configuration is also +handled by XEmacs. XEmacs virtual users are configured in the +＠file{/etc/mail/xemacs/virtusertable-xemacs} file, and installed by +running ＠code{make} in ＠file{/etc/mail}. This implicitly runs +＠file{sudo}; the necessary privileges are extended to XEmacs postmasters +by Tux. Aliases are configured in +＠file{/etc/mail/xemacs/aliases-xemacs}, and installed by running +＠code{sudo /usr/bin/newaliases}. -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. +Mailman has the usual set of aliases. Mailman itself is administered by +Tux. The XEmacs Handlers are maintained by XEmacs, and there is a +script in ＠code{/space/mailman} to restart the Mailman qrunners if the +Handlers are modified. ＠code{sudo} privilege is required. +＠c #### get the name of the script! -＠menu -* Release Schedule:: -* Release Prerequisites:: -* Updating NEWS:: -* Updating README:: -* Updating Version Number:: -* Updating ChangeLogs:: -* Tagging Releases:: -* Creating Tarballs:: -* Creating ＠value{XEMACSORG} Releases:: -* Updating the Tracker:: -* Announce the Release:: -* Updating the Emacs Repository:: -* Updating the Debian Package:: -* Updating the XEmacs Package:: -* Updating the Online Documentation:: -* Updating the Free Software Directories:: -* After the Release:: -＠end menu +Everything else runs as an appropriate user, and files are editable by +either members of the ＠samp{mailman} group, the ＠samp{xemacadm} group, +or the ＠samp{xemacweb} user. -＠node Release Schedule, Release Prerequisites, File Releases, File Releases -＠section Release Schedule +＠heading Handling Spam -＠c Edited: stephen 2005-01-18 +XEmacs lists are publicly advertised and open-post, and the archives are +publicly accessible. This results in fairly high levels of spam +directed at our lists. So far we've resisted the temptation to knuckle +under to the spammers by closing lists, ＠emph{etc.}. (Admittedly, a big +reason is the elderly Rube Goldberg contraption we use to manage the +lists, most of whose components don't support effective spam filtering.) -＠strong{Totally bogus for XEmacs historical practice, probably totally -unrealistic as future policy.} +The first line of defense is sendmail milters, administered by Tux.org. +These include the ClamAV virus scanner and a greylisting milter. -Here is a suggested schedule for a release: +A sendmail alias forwards each list's mail to the ＠samp{xemacweb} user, +which has a 4-stage ＠file{.procmailrc}. In the first stage, procmail +examines the message headers, and a few automatically approved posts are +directly forwarded to Mailman, while a large number of certified spams +are sent to the bitbucket. In the second stage, procmail filters the +post with ＠file{spamc}, and the ＠samp{X-Spam-Status} header is checked +for various conditions, and appropriate action taken. In the third +stage, procmail scans the message body for spam spoor that SpamAssassin +misses. In the fourth stage, procmail parses out the mailing list from +the ＠samp{X-XEmacs-List} header, and forwards the mail to an alias for +the Mailman wrapper. -＠quotation -＠multitable ＠columnfractions .3 .3 .4 +Besides some standard filters in Mailman itself, there is an +XEmacs-specific Handler ＠file{XEmacsSource.py}. +Basically this handler performs some extra checking for implicit +addresses (the list's posting address is not visible in the addressee +headers), and holds posts that don't satisfy the criterion. This is +necessary because the aliases for the Mailman wrapper are visible from +the outside, and a lot of spam simply bypassed the procmail and +SpamAssassin checks! Spam trapped by this handler is held for +moderation. It can be recognized by the reasons for hold in the Mailman +administration web interface, which are ``injected into the pipeline at +the wrong point'' and ``headers not consistent with this list''. -＠item ＠strong{Time} -＠tab ＠strong{Milestone} -＠tab ＠strong{Description} - -＠item T-4 weeks -＠tab Soft Freeze -＠tab -All P7 and higher features must be committed. -P6 features should be committed. -Any other new features destined for the release must be committed no -later than this time. -However, note that it is advisable not to release new user-visible -features this late in the game. It is better to add new features at -the beginning of a release cycle to allow for suitable usability -testing. -Testing commences. - -＠item T-3 weeks -＠tab Hard Freeze -＠tab -All P7 and higher bug fixes must be committed. -P6 bug fixes should be committed. -Testing continues. - -＠item T-2 weeks -＠tab Beta 1 -＠tab -Cut beta release. -Upload to ＠value{XEMACSORG}. - -＠item T-1 weeks -＠tab Beta 2 -＠tab -Cut beta release. -Upload to ＠value{XEMACSORG}. - -＠item T-0 weeks -＠tab Release! -＠tab -Cut release. -Upload to ＠value{XEMACSORG}. +Note that what we should do is fold the procmail filtering and archive +processing into the Mailman pipeline. This isn't too hard conceptually +In fact, with a little care we should be able to dispense with the +procmail invocation altogether, since procmail recipes are quite +straightforward to implement in Python. This might even decrease the +computational burden, as Mailman's qrunner daemons are long-lived +processes, so both the fork tax and the burden of compiling the regular +expressions will be amortized over hundreds, thousands, or more posts. -＠end multitable -＠end quotation -Once a release date has been determined, the milestones leading up to -that release should be posted as a news item (＠pxref{News}). -With frequent minor releases, omit the beta releases and -pre-announcement. +＠node xemacs-announce, xemacs-beta, Maintaining the Mailing Lists, XEmacs Mailing Lists +＠subsection The xemacs-announce Mailing List -＠node Release Prerequisites, Updating NEWS, Release Schedule, File Releases -＠section Release Prerequisites +＠strong{Somebody, write me!} -＠c Edited: stephen 2005-01-18 only to fix a makeinfo error -＠cindex Release Prerequisites -＠cindex Coding Conventions -＠cindex Emacs Lisp Coding Conventions -＠cindex Conventions, verification -＠cindex Verification, conventions -＠c #### is this relevant? -The first thing to do is to check the code for coding convention -compliance as described in section ＠ref{Philosophy}. +＠node xemacs-beta, xemacs-buildreports, xemacs-announce, XEmacs Mailing Lists +＠subsection The xemacs-beta Mailing List -Next, check for Emacs changes to XEmacs as described in section -＠ref{Updating the Emacs Repository}. +＠strong{Somebody, write me!} -＠node Updating NEWS, Updating README, Release Prerequisites, File Releases -＠section Updating NEWS -＠cindex NEWS -＠cindex news -＠cindex src -＠cindex Debian -When the ＠code{src} module is released (＠pxref{CVS Repository}), the -file ＠file{NEWS} needs to be updated. Separate the old news with -the new with a ＠kbd{C-l} and follow the existing format for -documenting user-visible changes only including New Features, New -Variables, and Bug Fixes. List ＠value{XEMACSORG} issues as ＠code{(closes SF -#123456)}, as well as third-party issues such as ＠code{(closes SF -#123456, Debian #123456)}. +＠node xemacs-buildreports, xemacs-cvs, xemacs-beta, XEmacs Mailing Lists +＠subsection The xemacs-buildreports Mailing List -In order to find what is appropriate for ＠file{NEWS}, several -things can be done. +＠strong{Somebody, write me!} -＠enumerate -＠item -Go to ＠uref{https://sourceforge.net/bugs/?group_id=13357, Bugs} and -search for all bugs whose status is Closed and group is CVS (no -documentation update needed) or status is Open, group is CVS, and -category is Documentation (documentation update needed but not -finished). -＠item -Repeat for -＠uref{https://sourceforge.net/tracker/?atid=363357&group_id=13357, -Feature Requests}. +＠node xemacs-cvs, xemacs-design, xemacs-buildreports, XEmacs Mailing Lists +＠subsection The xemacs-cvs Mailing List -＠item -＠cindex release-utils -Run the ＠code{release-utils --variable-changes ＠var{previous-tag}} to -produce a list of new and deleted variables suitable for inclusion in -＠file{NEWS}. +＠strong{Somebody, write me!} -＠item -Run ＠kbd{C-h m} in MH Folder and MH Letter modes in both the new and -old versions to show the key binding changes. -＠item -Search for ＠code{[0-9][0-9][0-9][0-9][0-9][0-9]} in the -＠file{ChangeLog} to get a list of SF numbers. -＠item -Use the ChangeLog. +＠node xemacs-design, xemacs-mule, xemacs-cvs, XEmacs Mailing Lists +＠subsection The xemacs-design Mailing List -＠end enumerate +＠strong{Somebody, write me!} -The previous steps usually catch most items. To use a finer sieve, use -the following commands. These assume that the last version of the XEmacs -package was 6.0. -＠example - cvs log -rmh-e-6_0 - cvs diff -rmh-e-6_0 -＠end example -See section ＠ref{Updating ChangeLogs} before checking in this file. +＠node xemacs-mule, xemacs-patches, xemacs-design, XEmacs Mailing Lists +＠subsection The xemacs-mule Mailing List -＠node Updating README, Updating Version Number, Updating NEWS, File Releases -＠section Updating README +＠strong{Somebody, write me!} -＠cindex README -Ensure that the target Emacs version is correct, as well as the -supported Emacs versions. -Update the version number in various places in the INSTALL section. +＠node xemacs-patches, xemacs-review, xemacs-mule, XEmacs Mailing Lists +＠subsection The xemacs-patches Mailing List -See section ＠ref{Updating ChangeLogs} before checking in this file. +＠strong{Somebody, write me!} -＠node Updating Version Number, Updating ChangeLogs, Updating README, File Releases -＠section Updating Version Number -＠set VERSIONFILE ＠file{$＠{srcdir(a)}/version.sh} -XEmacs version information is kept in the file -＠value{VERSIONFILE}. This file must be valid when sourced -by a POSIX shell and when included by a portable Makefile. +＠node xemacs-review, xemacs-winnt, xemacs-patches, XEmacs Mailing Lists +＠subsection The xemacs-review Mailing List -The first in a series of stable releases is a special case, because it -involves creation of a new stable branch and affects numbering of the -trunk as well. In the new stable branch, ＠value{VERSIONFILE} must -assign the empty value to ＠samp{emacs_is_beta}. The value ``0'' is -assigned to ＠samp{emacs_beta_version}. The next ＠emph{even} number -(which is ``0'' in the case that ＠samp{emacs_major_version} is bumped) -is assigned to ＠samp{emacs_minor_version}, and -＠samp{emacs_major_version} is bumped if that was authorized by the -XEmacs Review Board. The codename ＠samp{xemacs_codename} is assigned at -the discretion of the stable release engineer. +＠strong{Somebody, write me!} -At the same time, a new release of the trunk, identical except for -version information, is made. ＠emph{The version information is the same -as the stable release}, except that ＠samp{emacs_minor_version} is bumped -to the next ＠emph{odd} integer, and ＠samp{xemacs_codename} is assigned -at the discretion of the beta release engineer. -Release engineers usually choose a theme for codenames and make the -proposed series available in a file. The name ＠samp{emacs_beta_version} -probably could have been more aptly chosen, but it is a historical relic -of the fact that it was first used in the beta series, then adopted in -the stable branch. The name is not user-visible; the value of this -variable is called the patch level in stable branch documentation. -(a)strong{N.B.} Release engineers should avoid disturbing the order of -variables in ＠value{VERSIONFILE}. The variables -＠samp{emacs_kit_version}, ＠samp{infodock_major_version}, -＠samp{infodock_minor_version}, and ＠samp{infodock_build_version} are -used for version information of various non-＠value{PROJECT} releases, -and should be ignored. Both of these features are unclean, but users' -auxiliary tools (and some tools distributed by the ＠value{PROJECT}, -including ＠file{build.el} and ＠file{build-report.el} in some releases) -often depend on the syntax of this file to work correctly. In beta -releases, there is an optional variable ＠samp{xemacs_extra_name} which -is a string that is appended to the version string. It is currently -automatically updated, and used to identify the date of a CVS checkout. +＠node xemacs-winnt, , xemacs-review, XEmacs Mailing Lists +＠subsection The xemacs-winnt Mailing List -Except in cases involving creation of a new stable branch, update of the -version information simply requires bumping ＠samp{emacs_beta_version} -and assignment of a new ＠samp{xemacs_codename}. +＠strong{Somebody, write me!} -＠node Updating ChangeLogs, Tagging Releases, Updating Version Number, File Releases -＠section Updating ChangeLogs -＠cindex ChangeLog +＠c ########################################################################## +＠c #### I haven't seriously worked on the following material. -- stephen #### +＠c ########################################################################## -Add a ChangeLog entry to ＠emph{every} ChangeLog in the tree, marking the -release. The text of the first line should match this regexp: +＠node Support Requests, Bugs, XEmacs Resources on the Internet, Top +＠chapter Support Requests -＠example -XEmacs \d+\(?:\.\d+\)+\(?:-b\d+\)?\(?:"\(\w\|\s-\)+"\)? is released -＠end example +＠cindex Support Requests -＠node Tagging Releases, Creating Tarballs, Updating ChangeLogs, File Releases -＠section Tagging Releases +Support requests are made to ＠value{BETA-LIST}. Developers should read +the mailing list frequently, and after a period of inactivity, browse +the ＠uref{http://list-archive.xemacs.org/xemacs-beta/,recent archives}. -＠cindex tags -＠cindex CVS, tag -＠cindex version numbers -It is critical that a snapshot of the software is created each time -the software is released. In CVS, this is performed with tags. -Every series of stable releases must have a branch tag of the form -＠i{release-M-N}. The trunk has no branch tag. Every release must have -a fixed tag of the form ＠i{release-M-N-B}, where ＠var{M} is the major -number, ＠var{N} is the minor number, and ＠var{B} is the beta release or -patch number. A hyphen is used since one cannot use dots in CVS tag -names. +＠node Bugs, Feature Requests, Support Requests, Top +＠chapter Bugs -The stable release branch tag doubles as a tag of the most recent -release. While this is not quite true during the process of -accumulating patches to the branch, due to the conservative nature of -that process it seems very unlikely to cause trouble. Since the trunk -has no tag, and many beta testers would prefer to avoid checking out in -the middle of a series of related check-ins, a fixed tag of the form -＠i{release-M-N-current-beta} is used to identify the current beta -release. It is updated by a command like ＠samp{cvs rtag -F -r -release-M-N-B release-M-N-current-beta}. +＠strong{We don't have a tracker. We should. Describe what it should +look like here. References to ``The Tracker'' below were originally to +the MH-E tracker on SourceForge, since the MH-E developers' guide is +where this text came from.} -The packages have independent release schedules, determined by the -XEmacs package maintainer and the XEmacs Package Release Engineer. +＠cindex Bugs +＠cindex priority +＠cindex bugs, priority +Bug reports, feature requests, and discussions that are expected to lead +to bug reports or feature requests are created in The Tracker. Most +bugs should be set to a priority of 5. -＠node Creating Tarballs, Creating ＠value{XEMACSORG} Releases, Tagging Releases, File Releases -＠section Creating Tarballs +＠cindex xemacs-beta -＠cindex Creating Tarballs -＠cindex CVS Repository -＠cindex modules -＠cindex CVS, modules -＠cindex tarballs, naming +Developers should follow the ＠i{xemacs-beta} 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 transferred to +The Tracker. 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. -The modules in the CVS Repository (＠pxref{CVS Repository}) map to the -distribution tarballs as follows: +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. -＠quotation -＠multitable ＠columnfractions .4 .6 +The assignment of bugs in Bugs follows the honor system. If you see an +open bug that you think you could handle, assign the bug to yourself. +Bugs that remain open should be reviewed by a member of the +＠value{BOARD}, who should try to find a developer to work on the bug. -＠item ＠strong{Module} -＠tab ＠strong{Tarball} +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 +Tracker reports. If a documentation change is not required, set the status to +Closed. If a documentation change is required, set the category to +Documentation, and assign the bug to the documentation tsar, +leave the status Open, and set the priority to 3 to set it +aside in listings sorted by priority. -＠item src -＠tab mh-e-M.N.tgz +See ＠ref{Release Engineering} for a motivation of why this process is useful. -＠item doc -＠tab mh-e-doc-M.N.tgz +The rest of this section describes the categories and groups that might +be set up for the XEmacs project. Someday, when we get a tracker. -＠item contrib -＠tab mh-e-contrib-M.N.tgz +＠menu +* Category:: +* Status:: +* Group:: +* Resolution:: +＠end menu -＠end multitable -＠end quotation +＠node Category, Status, Bugs, Bugs +＠section Category -＠cindex tarballs, making -＠cindex tarballs, naming -＠cindex tags -＠cindex CVS, tags -＠cindex Makefile targets, dist -＠cindex version numbers +＠cindex category +＠cindex bug category -The tarballs listed in the table above are built as follows: +Several categories have been found useful in another project. They are +organized by +function. They include ＠i{General}, ＠i{UI}, ＠i{Security}, +＠i{Documentation}, and ＠i{Contrib}. -＠itemize +＠table ＠b -＠cindex CVS, co +＠item General -＠item If ＠var{module} has not been checked out -already, check it out: +＠cindex general bug category +＠cindex bug categories, general -＠example -export CVS_RSH=ssh -cvs -d -z3 $USER＠＠cvs.mh-e.sourceforge.net:/cvsroot/mh-e co -r ＠var{release} ＠var{module} -＠end example +The ＠dfn{General} category is used for bugs that do not belong in any of +the other categories. -＠item If ＠var{module} has been checked out -already, set the sticky tag for the release: +＠item UI -＠example -cvs update -r ＠var{release} -＠end example +＠cindex UI bug category +＠cindex bug categories, UI -＠item Build the tarball. +The ＠dfn{UI} category is used for bugs in the software that the user sees +such as font-lock, key definitions, menus, and customization. -＠example -cd ＠var{module} -make dist -＠end example +＠item Security -＠end itemize +＠cindex security bug category +＠cindex bug categories, security -The ＠code{make dist} command ensures that the tarball is named correctly -and that the tar extracts in a subdirectory that has the same name as -the tarball's prefix. For example, if ＠var{release} was mh-e-5_2, then -the tarball would be named mh-e-5.2.tgz and would extract into the -directory named mh-e-5.2. +The ＠dfn{Security} category is used for bugs in the security arena. +Although XEmacs includes little that could be called secure code, shell +modes handle authentication interactions, a few subprocesses (movemail) +have permissions that exceed the user's, and network-facing code could +have buffer overflows that could be exploited by an attacker. -＠node Creating ＠value{XEMACSORG} Releases, Updating the Tracker, Creating Tarballs, File Releases -＠section Creating ＠value{XEMACSORG} Releases +＠item Documentation -＠cindex Creating ＠value{XEMACSORG} Releases -＠cindex releases -＠cindex tarballs, making +＠cindex documentation bug category +＠cindex bug categories, documentation -First, create the tarballs (＠pxref{Creating Tarballs}). Then -＠uref{https://sourceforge.net/project/admin/editpackages.php?group_id=13357, -add the release} per the instructions in -＠uref{https://sourceforge.net/docman/display_doc.php?docid=6445&group_id=1#filereleasesteps, -The File Release System}. Be sure to check the box labeled -＠code{Preserve my pre-formatted text}. Use the entire ＠file{README} -file for the release notes and the appropriate section of the -＠file{NEWS} file for the Change Log. - -If there were any beta releases leading up to this release, -＠uref{https://sourceforge.net/project/admin/editreleases.php?package_id=11309&group_id=13357, -edit the release} and set the Status to Hidden. - -＠node Updating the Tracker, Announce the Release, Creating ＠value{XEMACSORG} Releases, File Releases -＠section Updating the Tracker - -＠cindex Updating the Tracker - -After XEmacs is released, update the tracker. First, change the group to -mh-e-doc-(a)var{m.n} (for example, mh-e-doc-1.3) for all open -＠uref{https://sourceforge.net/tracker/?group_id=13357&atid=113357, -bugs} and -＠uref{https://sourceforge.net/tracker/?group_id=13357&atid=363357&, -features} with a category of Documentation and a group of CVS. The -list is restricted to open issues since it is possible that an issue -was given a category of Documention for inclusion in the release -notes and then closed. Such an issue would not force a manual update. - -Then change the name of the group CVS to mh-e-(a)var{m.n} for both -＠uref{https://sourceforge.net/tracker/admin/index.php?group_id=13357&atid=113357&add_group=1, -bugs} and -＠uref{https://sourceforge.net/tracker/admin/index.php?group_id=13357&atid=363357&add_group=1, -features}. For example, when XEmacs version 6.0 is released, rename the -CVS group to mh-e-6.0. Then create a new CVS group. This should be -done for doc and contrib releases too. - -An exception to this occurs when releasing beta releases. The group -name in the series of beta releases leading up to the actual release -is reused. That way, in the end all the existing issues are left -pointing to the actual release rather than a beta. For example, CVS -would first be renamed to mh-e-6.1.90 which would in turn be renamed -to mh-e-6.1.91 which would in turn be renamed to mh-e-7.0. - -Another oddity occurs when you make a patch release. When you change -the name of the group from CVS to mh-e-(a)var{m.n.p}, you will probably -effect mainline work. So go back to -＠uref{https://sourceforge.net/tracker/?group_id=13357&atid=113357, -bugs} and -＠uref{https://sourceforge.net/tracker/?group_id=13357&atid=363357, -features}, and browse all issues with the new mh-e-(a)var{m.n.p} group -name. Perform a mass group name change from mh-e-(a)var{m.n.p} to CVS -for all issues that do not appear in the patch release. It may also be -easier to add a new group name of mh-e-(a)var{m.n.p} and set the group -of the items in the patch release to it. +The ＠dfn{Documentation} category is used for bugs in the documentation +arena. In addition, if there are any code changes made as a result of a +bug report or feature request that require changes to the documentation, +the category of that issue should be set to Documentation after the bug +has been fixed or the feature implemented. Set +the priority to 3 to set the issue aside in listings sorted by priority. -＠node Announce the Release, Updating the Emacs Repository, Updating the Tracker, File Releases -＠section Announce the Release +＠item Contrib -＠cindex Announce the Release +＠cindex contrib bug category +＠cindex bug categories, contrib -Now that the release is ready for download, announce it as described -in ＠xref{News}. +The ＠dfn{Contrib} category is used for all bugs in the contributed +software. -＠node Updating the Emacs Repository, Updating the Debian Package, Announce the Release, File Releases -＠section Updating the Emacs Repository +＠end table -＠c Edited: stephen 2005-01-19 +＠node Status, Group, Category, Bugs +＠section Status -＠strong{Needs review. Although on the face of it this obviously has -nothing to do with XEmacs, in fact there are probably hints here for -XEmacs release engineers.} +＠cindex status +＠cindex bug status -＠cindex Updating the Emacs Repository -＠cindex Emacs, updating +The bug ＠dfn{status} is divided into four sections: ＠i{Open}, +＠i{Closed}, ＠i{Deleted} and ＠i{Pending}. -The Emacs repository is updated by the project -admin. Other developers may skip this section. +＠table ＠b -＠cindex gnu.org -＠cindex CVS Emacs Repository -＠cindex Emacs CVS Repository -＠cindex Savannah +＠item Open -The project admin must have an account on the ＠i{gnu.org} machines, -and must also be given access to the Emacs CVS repository. This can be -accomplished by following these steps: +＠cindex open bug status +＠cindex bug status, open -＠table ＠emph +When bugs are initially created, they are marked ＠dfn{Open}. -＠item -Obtain a -＠uref{https://savannah.gnu.org/account/register.php, Savannah login}. +＠cindex discussing bugs +＠cindex bugs, discussing +＠cindex features, discussing -＠item -Become an Emacs developer by contacting one of the admins listed on -the ＠uref{https://savannah.gnu.org/projects/emacs/, Emacs main page}. +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. -＠item -Follow the instructions given in -＠uref{https://savannah.gnu.org/cvs/?group=emacs, the CVS instructions}. +Discussion about entirely new features should be opened in the Feature +Requests section (＠pxref{Feature Requests}) but otherwise handled in +the same way. -＠end table +＠item Closed -＠cindex emacs-devel -＠cindex mailing lists, emacs-devel -＠cindex mailman +＠cindex closed bug status +＠cindex bug status, closed -The project admin must also join the ＠i{emacs-devel} mailing list. -Send a note to ＠i{emacs-devel-request＠(a)gnu.org} or use the -＠uref{http://mail.gnu.org/mailman/listinfo/emacs-devel, Mailman -interface} to subscribe. +When all aspects of a bug have been fixed, including code and +documentation, the bug is marked ＠dfn{Closed}. -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. +When setting the status to Closed, the group should be set to Fixed, +Works For Me, Invalid, or Rejected. -＠cindex CVS, co +＠item Pending -First, check out the Emacs source: +＠cindex pending bug status +＠cindex bug status, pending -＠example - cvs -d $USER＠＠savannah.gnu.org:/cvsroot/emacs co emacs -＠end example +You can set the status to ＠dfn{Pending} if you are waiting for a +response from the tracker item author. When the author responds, the +status is automatically reset to that of Open. Otherwise, if the +author doesn't respond within 14 days, then the item is given a status +of Deleted. -If the Emacs source has already been checked out, ensure that the XEmacs -source is not locally modified. This is essential for the next step to -proceed accurately. If the install-emacs step described below had been -performed during testing leading up to the release, remove the -modified XEmacs files and run ＠code{cvs update} again. - -＠cindex import-emacs -＠cindex Makefile targets, import-emacs - -Next, ensure that there have not been any upstream changes to either -the source or documentation. If so, the changes will need to be -imported into the ＠file{src} and ＠file{doc} modules. This is done by -running: +＠item Deleted -＠example - make import-emacs -＠end example +＠cindex deleted bug status +＠cindex bug status, deleted -＠cindex EMACS_HOME -＠cindex environment variables, EMACS_HOME -＠cindex variables, EMACS_HOME -＠cindex install-emacs -＠cindex Makefile targets, install-emacs +If an items has been marked Pending, it will be marked ＠dfn{Deleted} +if the author of the item does not respond within 14 days. -Then install the sources with: +＠end table -＠example - cd src - make install-emacs -＠end example +＠node Group, Resolution, Status, Bugs +＠section Group -The ＠code{install-emacs} target copies the lisp files to -＠file{$EMACS_HOME/lisp/mh-e} and copies ＠file{NEWS} to -＠file{$EMACS_HOME/etc}. - -＠cindex EMACS_HOME -＠cindex environment variables, EMACS_HOME -＠cindex variables, EMACS_HOME -＠cindex install-emacs -＠cindex Makefile targets, install-emacs -＠cindex ChangeLog +＠cindex group +＠cindex bug group -Next, install the documentation with: +The bug ＠dfn{group} contains several items. They include: -＠example - cd doc - make install-emacs -＠end example +＠table ＠b -This target copies ＠file{mh-e.texi} to ＠file{$EMACS_HOME/man}. +＠item None -Update ＠code{$EMACS_HOME/etc/ChangeLog} and -＠code{$EMACS_HOME/man/ChangeLog}. Simply cite the XEmacs release. For -example: +Bugs are initially filed in this group. -＠example - * NEWS, NEWS: Upgraded to XEmacs version 6.1. -＠end example +＠item CVS* -and +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. -＠example - * mh-e.texi: Upgraded to XEmacs documentation version 1.3. -＠end example +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. -Update ＠code{$EMACS_HOME/etc/NEWS} by adding text similar to the -following: +＠item xemacs* -＠example - * Changes in Emacs 21.4 +Bugs in groups starting with ``xemacs'' have either been found in the +given version if the Status is Open, or fixed in the given version if +the Status is Closed. - ** XEmacs changes. +＠end table - Upgraded to XEmacs version 6.1. Upgraded to XEmacs manual version 1.3. - See NEWS for details. -＠end example +＠node Resolution, , Group, Bugs +＠section Resolution -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. +A bug can appear in various states: -Then check in the files like this: +＠table ＠b -＠example - cvs ci -m"Upgraded to XEmacs version 6.1. - See etc/NEWS and lisp/mh-e/ChangeLog for details." -＠end example +＠item Accepted -＠cindex emacs-devel -＠cindex mailing lists, emacs-devel +＠cindex accepted resolution +＠cindex resolution, accepted -Send a note to ＠i{emacs-devel＠(a)gnu.org}, with a cc to -＠i{xemacs-design＠(a)xemacs.org} with the details. The subject -should indicate that the software has been checked in: +The ＠dfn{Accepted} resolution means that QA has accepted the fix. +Since we don't have a QA department, it is unlikely that this will be +used in that fashion. Instead, it can be used to indicate that a +developer feels that a feature request (that someone else posted) has +merit. -＠example - XEmacs 7.4.4 checked in -＠end example +＠item Duplicate -The first paragraph should include the description on the -＠uref{https://sourceforge.net/projects/mh-e/, Summary} page, and the -text: +＠cindex duplicate resolution +＠cindex resolution, duplicate -＠example - Read on for more details. -＠end example +The ＠dfn{Duplicate} resolution means that this bug is a duplicate of +another. The status may be set to Closed. Be sure to add a note which +mentions the bug number that this bug is a duplicate of. If this bug +has some good information in it, the URL to this bug should be added +to the duplicate. -The second paragraph should contain: +＠item Fixed -＠example - Project home page at: http://mh-e.sourceforge.net/. -＠end example +＠cindex fixed resolution +＠cindex resolution, fixed -Finally, append the release notes. If only the manual is updated, then -the announcement should read closer to the one used in the ＠value{XEMACSORG} -news item. +The ＠dfn{Fixed} group is used to indicate a bug or feature request that +has been fixed. -After checking XEmacs into Emacs, run ＠code{make import-emacs} a second -time to put the new code on the Emacs branch. This makes it possible -to detect changes to XEmacs that an Emacs developer may make later. - -＠node Updating the Debian Package, Updating the XEmacs Package, Updating the Emacs Repository, File Releases -＠section Updating the Debian Package - -＠cindex Updating the Debian Package -＠cindex Debian Package, Updating -＠cindex Debian - -This task is the duty of Peter Galbraith <＠i{psg＠(a)debian.org}&gt;. It may -be useful to others to want to make an unofficial package of the CVS -tree. - -To build a Debian package, you'll need to have installed the Debian -package ＠code{build-essential} as well as those listed in the -＠code{Build-Depends-Indep:} line of the file ＠file{debian/control}. -Currently, there are the packages ＠code{debhelper} and ＠code{texinfo}. -The package ＠code{fakeroot} is also used below and ＠code{dpkg-dev-el} -is also useful. +＠item Invalid -＠example - apt-get install build-essential fakeroot debhelper texinfo dpkg-dev-el -＠end example +＠cindex not a bug resolution +＠cindex invalid resolution +＠cindex resolution, not a bug +＠cindex resolution, invalid -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: +The ＠dfn{Invalid} resolution is used to indicate the problem is with +the user. In other words, this is not a bug. See Works For Me. -＠example - rm `find . -name "*~"` - debian/rules source -＠end example +＠item Later -This will make a new file such as ＠code{mh-e_7.0.orig.tar.gz}. Unpack -it in a working directory and step into its top directory. Edit the -first line of the file ＠file{debian/changelog} to change the version -number between parentheses to something appropriate (e.g. -(a)code{7.0.+cvs-0}), or add another entry to the changelog and edit the -version number. If you installed the package ＠code{dpkg-dev-el} above, -simply do ＠kbd{C-c C-v} to insert this block and ＠kbd{C-c C-f} to -finalise the entry when done editing the version number. +＠cindex later resolution +＠cindex resolution, later -You can then create a Debian package by running: +The ＠dfn{Later} resolution is similar to the Postponed group, although +it connotates a longer delay. -＠example - fakeroot debian/rules binary -＠end example +＠item Out of Date -This creates ＠file{../mh-e_7.0.+cvs-0_all.deb} which can be installed -using standard Debian package management: +＠cindex out of date resolution +＠cindex resolution, out of date -＠example - dpkg -i ../mh-e_7.0.+cvs-0_all.deb -＠end example +The ＠dfn{Out of Date} resolution is similar to the term OBE (Overcome +By Events). In other words, the bug has not been fixed, but the code +has changed in ways that make it unnecessary to do so. -＠node Updating the XEmacs Package, Updating the Online Documentation, Updating the Debian Package, File Releases -＠section Updating the XEmacs Package +＠item Postponed -＠cindex Updating the XEmacs Package -＠cindex XEmacs Package, Updating -＠cindex XEmacs +＠cindex postponed resolution +＠cindex resolution, postponed -This task is the duty of XXX <＠i{XXX}>. It may be useful to others to -want to make an unofficial package of the CVS tree. +The ＠dfn{Postponed} resolution is similar to the Later group, although +it connotates a lesser delay. -The rest of this section needs to be completed. +＠item Rejected -＠node Updating the Online Documentation, Updating the Free Software Directories, Updating the XEmacs Package, File Releases -＠section Updating the Online Documentation +＠cindex rejected resolution +＠cindex resolution, rejected -＠c Edited: stephen 2005-01-19 -＠strong{Adrian, please review.} +The ＠dfn{Rejected} resolution means that QA has rejected the fix. +Since we don't have a QA department, it is unlikely that this will be +used in that fashion. Instead, it can be used to indicate that a +developer feels that a feature request does not have merit. -＠cindex Updating the Online Documentation -＠cindex online documentation, updating -＠cindex documentation, updating online -＠cindex CVS, update +＠item Remind -The entire XEmacs web site is kept in CVS, and automatically rebuilt by -the commit trigger. +＠cindex remind resolution +＠cindex resolution, remind -Thus, the basic procedure is similar to working on XEmacs source code. +The ＠dfn{Remind} resolution is similar to the Postponed and Later +groups, although it connotates an even lesser delay. -＠enumerate -＠item -Check out the ＠samp{xemacsweb} module. +＠item Wont Fix -＠item -Make the needed changes. +＠cindex wont fix resolution +＠cindex resolution, wont fix -＠item -Update the ChangeLog(s). +The ＠dfn{Wont Fix} resolution means that the XEmacs developers +acknowledge that the bug exists but are not going to fix it. Or the +developers will not implement a feature request. There is probably a +good reason for these things. -＠item -Test the changes with ＠code{make} to ensure that all ＠file{genpage} -commands are correct. Then use ＠code{make validate} to check that the -produced HTML is reasonably correct. +＠item Works For Me -＠item -Commit the workspace. -＠end enumerate +＠cindex irreproducible resolution +＠cindex resolution, irreproducible +＠cindex works for me resolution +＠cindex resolution, works for me -The XEmacs online documentation is mostly written in the ＠file{genpage} -language, which ensures a consistent interface for internal links via -special commands processed by the ＠code{genpage} script, and a -consistent overall format enforced by use of template files. Some of -the material, such as the online versions of the ＠emph{XEmacs User's -Guide} is generated directly from Texinfo, and checked in to CVS as HTML -rather than ＠file{genpage} source. +The ＠dfn{Works For Me} group is used to indicate a bug that cannot be +reproduced (irreproducible) and therefore cannot be fixed. See +Invalid. -The validator used by ＠code{make validate} is based on the PSGML -package. It is not perfect, but it is more convenient than the more -accurate online validators provided by the W3C and others. The -webmaster should use the online validators and link checkers regularly. +＠end table +＠node Feature Requests, Patch Queue, Bugs, Top +＠chapter Feature Requests +＠cindex Feature Requests -＠node Updating the Free Software Directories, After the Release, Updating the Online Documentation, File Releases -＠section Updating the Free Software Directories +Developers should check the +Feature Requests Trracker +occasionally for new feature requests and comment on the feature's +usefulness and integrity. Unless a positive comment has +＠c #### define "reasonable" +been added within a ``reasonable'' amount of time, a member of the +＠value{BOARD} +may set the status to Closed and the group to Wont Fix. ＠value{BOARD} +members should regularly check the list of requested features and prune +the oldest in this way to keep the list to a reasonable size. +＠c mh-e-devguide sez: +＠c will set the status to Closed and the group to Wont Fix. If the +＠c feature request is not closed, anyone may assign the request to +＠c themselves and implement the feature. -＠c Edited: stephen 2005-01-18 -＠strong{Add FreshMeat, at least.} +After incorporating the feature, update the feature request as +described in the previous section (＠pxref{Bugs}). -Update the ＠i{source-tarball} and ＠i{version} fields in the FSF/UNESCO -Free Software Directory (＠pxref{Free Software Directories}), as well as -the ＠i{touched} field. Update any other fields as necessary, including -the ＠i{updated} field. +＠node Patch Queue, News, Feature Requests, Top +＠chapter Patch Queue -＠node After the Release, , Updating the Free Software Directories, File Releases -＠section After the Release +＠cindex Patch Queue -＠cindex After the Release +Developers should check ＠value{PATCHES-LIST} +occasionally for new patches and comment on the patch's usefulness and +integrity. This will greatly help reviewers to review patches. Note +that developers who are active in commenting on patches and bug reports +are the main candidates when recruiting new reviewers. -After the release is complete, add the string ＠code{+cvs} to the -version number. ＠xref{Updating Version Number}. +＠c Legally speaking, patches that are less than 15 lines can usually be +＠c incorporated, although it is always best to try to incorporate them in +＠c a ``clean room'' environment. Do read +＠c ＠uref{http://www.gnu.org/prep/maintain_6.html#SEC6, Legally +＠c Significant Changes} for the details. -Then, define the next release. -Each developer goes through the bugs and feature requests and chooses -a month's worth of work for him to do. For each selected item, he -increases the priority to 7 and assigns the task to himself. Another -guideline for release size is that releases should only include 7 +/- -2 new features or bug fixes. - -The first month should be full of fervent activity. Development should -slow down in the second month while the new features are fine-tuned. -The third month is devoted to the release. ＠xref{Release Schedule}. It -is acceptable and often desirable to shorten each step in this cycle -in order to keep the number of release note bullet items to 7 +/- 2, -but in order to keep the releases fresh, it's probably not a good idea -to lengthen the process. - -If a new bug or feature arises that a developer wants to work on, the -developer sets the priority of that item to 7 and resets the priority -of one of his other items back to 5. This keeps the release from -growing without bound. - -The motivation for this schedule is to keep the iteration cycle short, -to keep from adding new features just before a release, and from the -user's point of view, to increase the timeliness and quality of -releases. It also limits the scope of the release, and makes it clear -when we're done. -＠node News, Surveys, File Releases, Top +＠node News, Surveys, Patch Queue, Top ＠chapter News -＠c Edited: stephen 2005-01-18 - ＠strong{Needs review.} ＠cindex News ＠＠ -3207,8 +3048,6 ＠＠ ＠example XEmacs m.n.p released - XEmacs contributed software m.n.p released - XEmacs manual m.n.p released ＠end example As only the first paragraph is shown on the ＠value{XEMACSORG} front page, it ＠＠ -3259,14 +3098,11 ＠＠ and doc releases, which lack release notes, should be closer to the news item. -The Emacs announcement is described in ＠ref{Updating the Emacs -Repository}. + ＠node Surveys, Free Software Directories, News, Top ＠chapter Surveys -＠c Edited: stephen 2005-01-18 - ＠strong{Interesting. Should we do this, maybe?} ＠cindex Surveys ＠＠ -3318,13 +3154,9 ＠＠ Finally, if any changes were made to the short or long descriptions, it is likely that the following will have to be updated: the -＠value{XEMACSORG} XEmacs project description (see -＠uref{https://sourceforge.net/project/admin/editgroupinfo.php?group_id=13357, -Editing the ＠value{XEMACSORG} Project Description}), the top-level -(a)file{index.php} file in the Project Website (＠pxref{Project -Website}), the ＠file{control} file in the Debian package -(＠pxref{Updating the Debian Package}), and the XEmacs package -(＠pxref{Updating the XEmacs Package}). +＠value{XEMACSORG} XEmacs project description in the top-level +(a)file{index.content} file in the Project Website (＠pxref{Project +Website}). ＠c #### Nuke this, but check whether the topics below need discussion. -- Graduate School of Systems and Information Engineering University of Tsukuba http://turnbull.sk.tsukuba.ac.jp/ Tennodai 1-1-1 Tsukuba 305-8573 JAPAN Economics of Information Communication and Computation Systems Experimental Economics, Microeconomic Theory, Game Theory