User: stephent Date: 05/02/01 17:08:36 Added: packages/xemacs-packages/general-docs/texi/xemacs xemacs-devguide.texi Log: New Developers Guide <87y8e89ses.fsf(a)tleepslib.sk.tsukuba.ac.jp&gt; Revision Changes Path 1.14 +4 -0 XEmacs/packages/xemacs-packages/general-docs/ChangeLog (In the diff below, changes in quantity of whitespace are not shown.) Index: ChangeLog =================================================================== RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/general-docs/ChangeLog,v retrieving revision 1.13 retrieving revision 1.14 diff -u -b -r1.13 -r1.14 --- ChangeLog 2004/12/22 21:51:15 1.13 +++ ChangeLog 2005/02/01 16:08:32 1.14 ＠＠ -1,3 +1,7 ＠＠ +2005-02-02 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/xemacs-devguide.texi: New file. + 2004-12-22 Norbert Koch <viteno(a)xemacs.org&gt; * Makefile (VERSION): XEmacs package 1.03 released. 1.1 XEmacs/packages/xemacs-packages/general-docs/texi/xemacs/xemacs-devguide.texi Index: xemacs-devguide.texi =================================================================== \input texinfo ＠c -*-texinfo-*- ＠c $Id: xemacs-devguide.texi,v 1.1 2005/02/01 16:08:35 stephent Exp $ ＠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 ＠c %**end of header ＠c Version variables. ＠set EDITION 0.5 ＠set UPDATED 2005-01-20 ＠set UPDATE-MONTH January, 2005 ＠c Other variables. ＠set XEMACSORG XEmacs.ORG ＠set PROJECT XEmacs Project ＠set HOMEPAGE ＠uref{http://www.xemacs.org/,XEmacs Project Website} ＠set BOARD XEmacs Review Board ＠set C-E-X the ＠i{comp.emacs.xemacs} Usenet newsgroup ＠set ANNOUNCE-LIST the ＠email{xemacs-announce＠(a)xemacs.org,XEmacs Announcements} mailing list ＠set BETA-LIST the ＠email{xemacs-beta＠(a)xemacs.org,XEmacs Beta} mailing list ＠set DESIGN-LIST the ＠email{xemacs-design＠(a)xemacs.org,XEmacs Design} mailing list ＠set REVIEW-LIST the ＠email{xemacs-review＠(a)xemacs.org,XEmacs Review} mailing list ＠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 ＠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 ＠quotation The ＠cite{XEmacs Developers Guide} is free documentation; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. The ＠cite{XEmacs Developers Guide} is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. The GNU GENERAL PUBLIC LICENSE appears as an appendix to this document. You may also request a copy by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ＠end quotation ＠end copying ＠setchapternewpage odd ＠dircategory XEmacs Editor ＠direntry * XEmacs Developers Guide: (xemacs-devguide). UNOFFICIAL EARLY DRAFT. ＠end direntry ＠titlepage ＠title The XEmacs Developers Guide ＠subtitle Edition ＠value{EDITION} ＠subtitle ＠value{UPDATE-MONTH} ＠author Stephen J. Turnbull ＠page ＠vskip 0pt plus 1filll ＠insertcopying ＠end titlepage ＠contents ＠ifnottex ＠node Top, Acknowledgments, (dir), (dir) ＠top The XEmacs Developers Guide ＠insertcopying ＠end ifnottex ＠cartouche ＠strong{This document is under development.} The current version contains a lot of text drawn from the ＠emph{MH-E Developers Guide} which is inapplicable to the ＠value{PROJECT}. Those parts which have been adjusted to reflect ＠value{PROJECT} practice are based on the opinions of the author(s) as to best practice and desirable policy, and ＠strong{are not yet approved as official policy}. ＠end cartouche ＠menu * Acknowledgments:: * Introduction:: * Philosophy:: * The Work Roles:: * The Work Flow:: * XEmacs Resources on the Internet:: Nodes borrowed from other projects, not adapted to XEmacs: * Support Requests:: * Bugs:: * Feature Requests:: * Patch Queue:: * File Releases:: * News:: * Surveys:: * Free Software Directories:: * Copying:: * Index:: ＠detailmenu --- The Detailed Node Listing --- People and the Project * Beta Tester:: * Committer:: * XEmacs Package Maintainer:: * XEmacs Reviewer:: * Meta-Maintainer:: * Release Engineer:: * Jobs List:: Committer * Commit Access:: * Committer Welcome Message:: XEmacs Reviewer * Appointing New Reviewers:: * Welcoming New Reviewers:: The Life Cycle of a Patch * About Copyright Assignment:: * Scratching That Itch:: * Get the Sources:: * Write Low-Profile Code:: * Test Your Changes:: * Add a ChangeLog Entry:: * Create the Patch:: * Submit the Patch:: * Patch Review:: * Committing the Patch:: * Dispute Resolution:: Add a ChangeLog Entry * ChangeLogs:: * Log Messages:: Submit the Patch * Proposed Optional Alternate Procedure for Reviewers:: Patch Review * Commit-and-Review:: Committing the Patch * Proposed Alternative Procedure:: XEmacs Resources on the Internet * Project Website:: * CVS Repository:: * comp.emacs.xemacs:: * xemacs-beta:: * xemacs-design:: * xemacs-patches:: * xemacs-mule:: * xemacs-winnt:: Nodes borrowed from other projects, not adapted to XEmacs Bugs * Category:: * Status:: * Group:: * Resolution:: File Releases * Release Schedule:: * Release Prerequisites:: * Updating NEWS:: * Updating README:: * Updating Version Number:: * Updating ChangeLogs:: * Tagging Releases:: * Creating Tarballs:: * Creating ＠value{XEMACSORG} Releases:: * Updating the Tracker:: * Announce the Release:: * Updating the Emacs Repository:: * Updating the Debian Package:: * Updating the XEmacs Package:: * Updating the Online Documentation:: * Updating the Free Software Directories:: * After the Release:: ＠end detailmenu ＠end menu ＠node Acknowledgments, Introduction, Top, Top ＠chapter Acknowledgments ＠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 General Public License. The best practices exemplified by Martin Buchholz and Vin Shelton are the primary reference for the section on release engineering of the core XEmacs distribution. ＠node Introduction, Philosophy, Acknowledgments, Top ＠chapter Introduction ＠c Edited: stephen 2005-01-18 ＠cindex Introduction ＠cindex ＠value{XEMACSORG} So, you want to be an XEmacs developer! You've already taken the essential step by showing enough interest to read this document. This document describes other steps you may wish to take to participate more effectively. First, it captures the philosophy of the development team. There is then a section for each resource in the ＠value{PROJECT} that developers may want to use or need to change. In other words, this is the single sheet of music that all the XEmacs developers are playing. Note that it is about project organization and administration, not about the code base. For coding standards and techniques, XEmacs has a separate manual, ＠ref{Top, The XEmacs Internals Manual, , internals}. ＠cindex mailing lists, xemacs-design ＠cindex xemacs-design And remember, this is your document. If you think something is bogus, start a movement on ＠value{DESIGN-LIST}. One of the tenets of the philosophy is rough consensus. If you can get a rough consensus to agree with your point of view, then the document shall be changed accordingly. ＠cartouche ＠strong{This document is under development.} The current version contains a lot of text drawn from the ＠emph{MH-E Developers Guide} which is inapplicable to the ＠value{PROJECT}. Those parts which have been adjusted to reflect ＠value{PROJECT} practice are based on the opinions of Stephen Turnbull as to best practice and desirable policy, and ＠strong{are not yet approved as official policy}. Feel free to submit patches to ＠value{PATCHES-LIST}. Please try to review and edit a whole node at a time. They're short; it's not that great a burden. XEmacs Reviewers: If you review and approve of a node as is, please add a comment just below the ＠samp{＠＠node} and sectioning commands in the node like ＠example ＠＠c Reviewed: ＠var{name} ＠var{date} ＠end example Otherwise, edit the node and add a comment ＠example ＠＠c Edited: ＠var{name} ＠var{date} ＠end example ＠end cartouche ＠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!} This chapter discusses the philosophy and principles of the XEmacs project. The first section covers our coding philosophy, while the second section summarizes the principles of the team that have evolved over time. ＠heading Code The core philosophies of the XEmacs project regarding the code are as follows: ＠enumerate ＠item Keep the code small and fast ＠item Refrain from adding lots of code to the codebase that would be better served with hooks. ＠item In order to provide maximum compatibility with other MH interfaces and MH itself, XEmacs should use MH itself as much as possible. XEmacs is, after all, a interface to MH and therefore should not implement MH. ＠item XEmacs should be easy to use out-of-the-box for new users. ＠end enumerate That last priority struggles mightily with the other priorities. For example, the user ＠i{could} write his own hooks for many features. However, the average user is not going to do so. Indeed, the customization buffer may be too intimidating and providing radio buttons and checkboxes in the menu may be the way to go in some cases. ＠cindex customize In a less contentious way, making XEmacs easier to use may mean better integration with other software packages (such as ＠code{tm} or ＠code{goto-addr}). Or pre-written hook functions could be provided. We should get as much mileage out of ＠code{customize} as we can to reduce the amount of code that users have to write. One other subject related to philosophy is to what constitutes a major release. Major releases signal to the user that the new version may not work as it did before and that reading of the release notes is mandatory. Major releases occur when incompatible changes are made that are visible to the user. Types of changes include changing the name of or deleting functions, key bindings, and customization variables. The converse is true; these sorts of changes should not be applied to minor releases. By itself, merely adding a new feature does not just justify a major release. On the other hand, a major release is called for if the code is completely rewritten, even if the user cannot notice any difference. ＠heading Guiding Principles The guiding principles of the XEmacs developers are: ＠enumerate 1 ＠item While we all are scratching an itch on this project, we also have very few users and a great desire to have more. Our users are sacrosanct; we will go the extra distance to please our users. ＠item Using vulgar language towards our users and/or developers is unacceptable. ＠item The team makes decisions by consensus through articulated arguments. If one wants to express an opinion, they do it by presenting evidence to support their claim in a respectful way, and not by insulting others' points of view. While it takes some time and effort to articulate the reasons behind one's point of view, we enjoy the process and often gain a better understanding of the issues by the end. ＠item We are all committed to a high-quality product. We have no artificial deadlines, so if it takes an extra iteration or two to find the optimal solution to a problem, then we do it. ＠item We believe in collective ownership. We keep our egos in check and say "Thank you" to a colleague when he rewrites our code. He'll thank you when you fix his. ＠item Finally, we're here to have fun. ＠end enumerate ＠heading Coding Conventions Coding conventions are described in detail elsewhere. ＠c #### Make this xref more precise. ＠xref{Top, Internals Manual, , internals}. ＠c #### Move these somewhere more appropriate Here are a few additional references that you might want to check out. ＠cindex Coding Conventions ＠cindex Emacs Lisp Coding Conventions ＠cindex Library Headers ＠cindex Conventions, verification ＠cindex Verification, conventions ＠findex ＠code{lm-verify} ＠findex ＠code{checkdoc} ＠cindex ＠file{lisp-mnt} The (GNU) Emacs Lisp Manual ＠ifnothtml ＠ref{Tips, Tips and Conventions, , elisp}. ＠end ifnothtml ＠ifhtml ＠uref{http://www.sunsite.ualberta.ca/Documentation/Gnu/emacs-lisp-ref-21-2.7/html_node/elisp_708.html, Tips and Conventions}. ＠end ifhtml ＠strong{Please ensure that the copyright notice of every file accurately reflects your contribution, whether you have assigned your copyright or not. This will aid future project admins greatly if there ever is a merger.} You ＠strong{must} reference the GPL correctly in every file. Manuals must also follow these rules, except that for historical reasons they have various different licenses. ＠emph{Be careful}: it is typically ＠strong{not} permissible to mix excerpts from different documents with each other, or with XEmacs code, unless they have ＠emph{identical} licenses. All code and data files must be licensed under the GPL (or a compatible license) so that they can be added to XEmacs, and others may modify them. Documentation files must be licensed under an approved free license or an OSI-approved open source license. Where possible, GPL-compatible licenses are preferred. 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 ＠ifnothtml ＠ref{Library Headers, , , elisp}, ＠end ifnothtml ＠ifhtml ＠uref{http://www.sunsite.ualberta.ca/Documentation/Gnu/emacs-lisp-ref-21-2.7/html_node/elisp_713.html, Library Headers} ＠end ifhtml are present. The ＠code{checkdoc} function should be run before check-ins as well. All errors must be fixed. You should also ＠emph{read the comments} in the ＠file{lisp-mnt} library source. Any steps needed to build or disseminate releases should be found in Makefiles (or in this document). In other words, there is to be no magic stored only in someone's head. ＠node The Work Roles, The Work Flow, Philosophy, Top ＠chapter The Work Roles ＠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 share the program with anybody you like, and even people you don't like! People being what they are, the detailed goals differ from one to another, and they end up in conflicts between one person's goals and another's. Allowing people to fill roles that suit them, and creating a work flow that lets them share the products of their work without getting in each other's ways, are the foundations of the project. ＠heading People and the Project ＠cindex Definitions ＠cindex developer ＠cindex contributor A ＠dfn{developer} or ＠dfn{contributor} is anyone who wants to participate in improving XEmacs. Presumably you do, because you're reading this ＠emph{Guide}. Well then---presto-chango! you're a developer. That doesn't mean that some developers don't have more privileges than others, that all contributions are accepted, or that some contributions aren't bigger than others. What it means is that the ＠value{PROJECT} is intended to facilitate individual contributions and cooperation among contributors. It means that in the ＠value{PROJECT} we don't make a sharp distinction between ``users'' and ``developers.'' Some important contributors never even submit code to the project; they simply participate in the newsgroups and mailing lists, giving advice based on their experience to other users. Here are some of the better defined roles. Most are defined by reference to ＠value{PROJECT} resources. ＠table ＠dfn ＠item Developer ＠itemx Contributor You. Me. Generally, anybody who wants to help improve XEmacs. ＠xref{The Work Flow}. ＠item User You. Me. Generally, anybody whose needs are being served by XEmacs. Specifically, someone who can tell us how to do it better. Often, someone who advises other users on mailing lists or Usenet. ＠xref{XEmacs Resources on the Internet}. ＠item Beta tester A user currently not active as a code contributor, but willing to reinstall XEmacs and its packages regularly, and report any problems. Should participate in ＠value{BETA-LIST}. ＠xref{xemacs-beta}. ＠item Committer A developer with write access to the XEmacs CVS repository, which may be restricted to specified modules. ＠xref{Committer}. Should participate in ＠value{BETA-LIST} ＠ref{xemacs-beta}, and ＠value{PATCHES-LIST} ＠ref{xemacs-patches}. ＠item Package maintainer A committer with responsibility for integrating a separately maintained module containing a set of optional libraries with XEmacs. The module often constitutes a well-defined application, such as an MUA. ＠xref{XEmacs Package Maintainer}. ＠item Reviewer A developer who may authorize developers, including himself, to write to the XEmacs CVS repository. ＠xref{XEmacs Reviewer}. Should participate in ＠value{BETA-LIST} ＠ref{xemacs-beta}, ＠value{DESIGN-LIST} ＠ref{xemacs-design}, and ＠value{PATCHES-LIST} ＠ref{xemacs-patches}. ＠item XEmacs Review Board The reviewers as a group, responsible for delegating access to ＠value{PROJECT} resources to developers. A self-selecting cabal. The current members are noted on the ＠uref{http://www.xemacs.org/Develop/jobs.html,＠emph{Job List}}. ＠xref{Jobs List}. ＠item Chairman of the Board ＠item CEO ＠item Maintainer ＠item Benevolent Dictator for Life Call it what you like, we don't have one any more, by deliberate choice. ＠item Meta-maintainer ＠item Mr. XEmacs The reviewer responsible for trying to keep track of what isn't getting done, and finding someone to do it. The latter title allows him to tell his mother how important he is. More seriously, the meta-maintainer often functions as a spokesman for the Board or the project as a whole. Should be highly visible on ＠value{C-E-X} ＠ref{comp.emacs.xemacs} and ＠value{BETA-LIST} ＠ref{xemacs-beta}. ＠item Release engineer ＠item Stable release engineer ＠item Package release engineer Responsible for the quality control and adminstrative details of distributing some coherent package of functionality. The ＠dfn{stable release engineer} manages the core distribution, including the build infrastructure, the Lisp and display engine, and the functions typical of a programmer's editor, though very powerful. The ＠dfn{package release engineer} manages the various unbundled applications, the build infrastructure, and the network-based download and install functionality for them. Must participate in ＠value{PATCHES-LIST} ＠ref{xemacs-patches}. ＠c #### Write nodes for these posts! ＠item Postmaster ＠item Webmaster ＠item CVS Manager Administrators of the various Internet-based services important to XEmacs users and developers. ＠c #### Write nodes for these posts! ＠item Miscellaneous The ＠emph{Jobs List} describes a number of other idiosyncratic positions and tasks in the ＠value{PROJECT}. It also lists the current members of the ＠value{BOARD}. ＠xref{Jobs List}. The most recent version can be found ＠uref{http://www.xemacs.org/Develop/jobs.html,on the website}. ＠end table ＠menu * Beta Tester:: * Committer:: * XEmacs Package Maintainer:: * XEmacs Reviewer:: * Meta-Maintainer:: * Release Engineer:: * Jobs List:: ＠end menu ＠node Beta Tester, Committer, The Work Roles, The Work Roles ＠section Beta Tester ＠cindex beta tester ＠cindex tester, beta ＠cindex xemacs-beta mailing list ＠cindex mailing list, xemacs-beta ＠cindex xemacs-buildreports mailing list ＠cindex mailing list, xemacs-buildreports ＠cindex xemacs-design mailing list ＠cindex mailing list, xemacs-design ＠findex report-xemacs-bug ＠findex build-report An extremely important role is that of ＠dfn{beta tester}. Since the XEmacs CVS repository is open for anonymous read access, beta testers do not get special access to unpublished code. Rather, beta testers ＠c need ＠xrefs for bug and build reports contribute by submitting bug reports on problems, and build reports to give the community information about the variety of platforms and features XEmacs is being configured for. Bug reports are submitted to ＠value{BETA-LIST}, preferably via ＠kbd{M-x report-xemacs-bug RET}. Build reports are submitted to ＠value{BUILDREPORTS-LIST} via the ＠kbd{M-x build-report RET} utility. Testers may also wish to subscribe to ＠value{DESIGN-LIST}, to lobby for their favorite new features. However, for those who do wish to make contributions to the collection of bytes that we call ``XEmacs'', there are a number of formal roles, with powers and privileges that make it easier to make them. ＠node Committer, XEmacs Package Maintainer, Beta Tester, The Work Roles ＠section Committer ＠cindex committer ＠c MH-E says that committers may be _assigned_ bugs A ＠dfn{committer} is one who is authorized to check in approved changes into the CVS repository, including changes to private branches they may maintain. Developers who do not have CVS access contribute by submitting patches to ＠value{PATCHES-LIST}. Commit access is generally given to those who have submitted several good patches, to ``well-known'' developers on request, and to XEmacs package maintainers. ＠menu * Commit Access:: * Committer Welcome Message:: ＠end menu ＠node Commit Access, Committer Welcome Message, Committer, Committer ＠subsection Commit Access ＠c Edited: stephen 2005-01-18 ＠cindex commit access ＠cindex cvs.xemacs.org committer accounts There are a few minor prerequisites to get out of the way. The first is to ＠email{cvs-manager＠(a)xemacs.org,request an account at ＠i{cvs.xemacs.org}}, and the second is to ＠uref{http://www.xemacs.org/Lists/#xemacs-beta, subscribe to the XEmacs Beta mailing list}. ＠cindex XEmacs User's Guide ＠cindex manuals, XEmacs ＠cindex XEmacs Lisp Reference ＠cindex manuals, XEmacs Lisp ＠c #### fix these urefs!! Developers should be familiar with the ＠uref{http://www.xemacs.org/Documentation/,XEmacs Lisp Manual} ＠ifinfo ＠xref{Top, XEmacs Lisp Reference, , lispref}. ＠end ifinfo as well as the ＠uref{http://www.xemacs.org/Documentation/,XEmacs Manual}. ＠ifinfo ＠xref{Top, XEmacs User's Guide, , xemacs}. ＠end ifinfo ＠cindex xemacs-design mailing list ＠cindex mailing lists, xemacs-design ＠cindex committer If you think that you may contribute enough to want access to the CVS repository, request access from the ＠email{cvs-manager＠(a)xemacs.org,CVS Administrator}. Generally speaking, if you have contributed to the ＠value{PROJECT} mailing lists and ＠i{comp.emacs.xemacs} newsgroup over the years, you will be given CVS privileges within a few days. If you are new, you may need to find a sponsor on the ＠value{BOARD} to vouch for you. ＠cindex pictures of developers ＠cindex developers, pictures ＠cindex information about developers ＠cindex developers, information about On a less serious note, the ＠code{about-xemacs} command gives information, including photos, about developers past and present. Submit a patch to ＠file{lisp/about.el} and an image that represents you (as both a monochrome PNG and a color PNG) to ＠value{PATCHES-LIST}. ＠node Committer Welcome Message, , Commit Access, Committer ＠subsection Committer Welcome Message ＠c #### The information in this message should be parsed out into Work Flow. ＠cindex committers, welcoming ＠cindex welcoming committers Here's a typical welcome message for a new package maintainer. The changes appropriate to a generic committer should be pretty obvious. ＠display To: "Newbert Committer, redtape Package Maintainer" <newbie＠(a)xemacs.org&gt; CC: XEmacs Review Board <xemacs-review＠(a)xemacs.org&gt;, newbert.committer＠(a)xemacs.org, newb.committer＠(a)xemacs.org, newbie＠(a)general-conglobulation.com Subject: Welcome to The XEmacs Development Team. Hi Newbie! On behalf of the XEmacs Review Board, I'd like to welcome you to the team as our new redtape maintainer. We really appreciate the time and effort you put into redtape and we'd like to thank you very much for taking on this important role. The first thing that you should notice is that you have received 4 copies of this message. One to your existing email address, and one each to your 3 new xemacs.org addresses. You can use the xemacs.org addresses for any XEmacs related purpose. Please note that this is neither a requirement or a restriction. Some of our developers rarely use their xemacs.org email address, while others use theirs for most things. At this point, Newbie, I'd suggest that you subscribe to a couple of our mailing lists, if you haven't already done so. xemacs-beta (for all kinds of code discussion) xemacs-patches (this is where all patches are sent) You can subscribe to these (and the other XEmacs mailing lists) at <http://www.xemacs.org/Lists/>;. Or via email, to: xemacs-beta-request＠(a)xemacs.org xemacs-patches-request＠(a)xemacs.org With "subscribe" (sans quotes) in the body of the emails. It also may be worth your while to monitor comp.emacs.xemacs if you have Usenet access. Here are a few guidelines that should make things run fairly smoothly for all those involved. CVS === Getting hold of your code from CVS: ---------------------------------- CVS_RSH=ssh cvs -z3 -d :ext:xemacs＠＠cvs.xemacs.org:/pack/xemacscvs co redtape Which will get just the redtape package. You can get all the packages with the module name "packages". I'd strongly suggest that you get the whole packages tree as usually packages require some functionality from other packages. But be warned, the packages tree is quite big (80+ MB as of 11/2002). Committing patches to CVS: ------------------------- My recommendation would be to use the excellent PCL-CVS package. It makes life a whole lot easier. Also, 'patcher.el' and 'patch-keywords.el' from the xemacs-devel package are both excellent libraries that can make things a lot easier for you when it comes to creating and submitting patches. Building ======== For a quick start to building packages, see INSTALL under the packages/ dir you've checked out from CVS. Patches ======= All changes must be documented by a patch sent to the xemacs-patches mailing list. The patch must be accompanied by a ChangeLog. The appropriate format is that generated by 'M-x add-change-log-entry'. This convenient function also automatically determines file and function containing the change, finds the appropriate ChangeLog file, and formats the entry for you in the standard style. Patches must be context diffs, preferably in diff -u format. ChangeLogs should be in plain text or diff -U 0 format. Documentation is being prepared and will be available under <http://www.xemacs.org/Develop/>;. One advantage of having all changes documented on xemacs-patches is that of the "many eyes" principle. Everyone on the XEmacs Review Board actively monitors the xemacs-patches mailing list and will generally look over any patch that falls into their area of expertise. We've caught many, otherwise overlooked, bugs simply because there has been another set of eyes look at a patch. As the maintainer of redtape, Newbie, any patches that you submit for redtape are automatically pre-approved. And you are the final authority on any patches submitted against the redtape package, which also includes patches from the XEmacs core developers. Basically what I'm saying, Newbie, is that it is your code and you shouldn't need our permission to make changes to it. It's up to us to look at your patches and yell if we think there is something wrong. Be aware though, that the XEmacs Packages Release Manager is the final authority on packaging infrastructure. And it is XEmacs policy to respect the wishes of the upstream maintainer, whether that is you or some other party. As the XEmacs Packages Release Manager, I'd like to add a couple of things here: 1) The packages CVS repository is a "stable" branch, please do all that you can to keep it that way. 2) In the Makefile you'll see "VERSION=" and "AUTHOR_VERSION=", please don't ever alter the former. We do that as part of the package release process. 3) When you update redtape in CVS it'd be great if you could either drop me a quick email or post to xemacs-beta saying that redtape is ready for release. Here's a brief rundown of how a package gets released: ----------------------------------------------------- You - hack hack hack - cvs diff -u > cool-new-patch.diff - submit to xemacs-patches - unless there are objections, or if it's "obviously correct", commit to CVS Us - cvs update - build new version of redtape - upload to the "Pre-Release" directory of ftp.xemacs.org - announce release on xemacs-beta - time passes (no complaints about buggy redtape package) - move redtape package to the main packages directory on FTP site - announce release on xemacs-announce (which goes to xemacs-beta and comp.emacs.xemacs) I think that fairly well covers most things, the only other thing I'd like to mention is: Have fun! And don't restrict your involvement to just redtape, if you notice anything else that could do with some help, jump right in. Once again, Newbie, thank you for taking on this very important role for us. And welcome to the Team! Oldbert Reviewer, XEmacs Package Release Manager. ＠end display ＠node XEmacs Package Maintainer, XEmacs Reviewer, Committer, The Work Roles ＠section XEmacs Package Maintainer ＠cindex XEmacs package maintainer ＠cindex maintainer, XEmacs package ＠cindex upstream maintainer ＠cindex maintainer, upstream A special kind of committer is the ＠dfn{XEmacs package maintainer}. Much Emacs functionality comes in the form of add-on Lisp libraries. Starting with XEmacs 20.4, most applications were unbundled from XEmacs, and are now separately maintained, with their own release cycles, and often separate development organizations. An ＠dfn{XEmacs package maintainer} is responsible for maintenance of the infrastructure required to seamlessly integrate one or more libraries into XEmacs and provide for convenient distribution and administration of the package by users. An XEmacs package maintainer approves patches for the package he maintains, just as reviewers do for the rest of the code base. ＠xref{XEmacs Reviewer}. Only in rare cases (such as bugs causing data loss or affecting security or stability of XEmacs) should reviewers, other than the XEmacs Package Release Engineer, approve patches to packages which have a designated maintainer. Instead, they should ＠samp{RECOMMEND} patches that they like. ＠xref{Patch Review}. In other words, each unbundled package, in principle, has a separate development organization. It may be hosted by the ＠value{PROJECT}, or it may have its own resources. A package's XEmacs maintainer may be an XEmacs developer, the upstream maintainer of the Lisp libraries, or a liaison drawn from either project. Once the appointment is approved by the upstream maintainer and the XEmacs Review Board, the XEmacs package maintainer is given commit access restricted to the package's repository, which is a subdirectory of the XEmacs packages repository. XEmacs package maintainers are ＠emph{not} responsible for the administrative aspects of releasing an XEmacs package of their application; this work is done by the XEmacs Package Release Engineer. Of course the package maintainer does have control over the decision to release. ＠node XEmacs Reviewer, Meta-Maintainer, XEmacs Package Maintainer, The Work Roles ＠section XEmacs Reviewer ＠cindex reviewer ＠cindex XEmacs Review Board ＠cindex maintainer ＠cindex committer ＠cindex xemacs-patches mailing list ＠cindex mailing list, xemacs-patches ＠cindex xemacs-review mailing list ＠cindex mailing list, xemacs-review ＠cindex maintainer, nonexistence of authoritative ＠cindex nonexistence of authoritative maintainer A ＠dfn{reviewer} is a developer who may approve or veto patches proposed for application to the CVS trunk. They are expected to subscribe to ＠value{PATCHES-LIST}, the channel for submission of patches to the XEmacs code base and documentation sources. The collection of reviewers constitutes the ＠dfn{XEmacs Review Board}, which is responsible for arbitrating conflicts among reviewers, for relations to other projects (specifically the GNU Emacs project), for changes to the development process described in this ＠emph{Guide}, and for giving access to ＠value{PROJECT} resources to developers, including selecting new reviewers. ＠c #### ＠xref{XEmacs Review Board}. Unlike many projects (in particular, GNU Emacs), the ＠value{PROJECT} does not have a single authoritative ＠dfn{maintainer}. Policy discussions are conducted on the ＠value{REVIEW-LIST}. Only reviewers are subscribed, but any developer may post. Reviewers are recruited (or are volunteers) from the ranks of the committers. The primary qualification for reviewer is a track record of submitting code and other contributions, constructive criticism of others' patches, and general discussion on the xemacs-patches, xemacs-beta, and xemacs-design mailing lists. In other words, if you act like a reviewer, you're likely to be asked to be one. ＠menu * Appointing New Reviewers:: * Welcoming New Reviewers:: ＠end menu ＠node Appointing New Reviewers, Welcoming New Reviewers, XEmacs Reviewer, XEmacs Reviewer ＠subsection Appointing New Reviewers ＠c Created: stephen 2005-01-19 ＠strong{This node needs improvement!!} ＠cindex ＠value{BOARD} ＠cindex appointing reviewers ＠cindex reviewers, appointing The ＠value{BOARD} is a self-maintaining cabal. New reviewers are appointed when the Board feels it would improve the project. ＠node Welcoming New Reviewers, , Appointing New Reviewers, XEmacs Reviewer ＠subsection Welcoming New Reviewers ＠cindex reviewers, welcoming ＠cindex welcoming reviewers ＠c #### The information in this message should be parsed out into Work Flow. When a new reviewer is appointed, a representative of the ＠value{BOARD} (typically the meta-maintainer or the mentor of the new reviewer) sends a welcome message to the new reviewer. Here's a sample. ＠display To: Newbert Reviewer <newbie＠(a)xemacs.org&gt; CC: XEmacs Review Board <xemacs-review＠(a)xemacs.org&gt; Subject: Welcome to the Review Board Dear Newbie, Welcome to the XEmacs Review Board. Your main responsibility as a reviewer is to subscribe to the xemacs-patches mailing list, and review patches you feel you have expertise on. This would include the Snufflopagus OS support and the Round-the-World-Tour package, of course. Any additional reviewing you can do would be very welcome. If you need to take time off, you can do so freely. If it is going to be a substantial block of time, it would be helpful if you would advise the review board so that other reviewers can pick up on patches to areas that you would normally review. Our formal Reviewer's Guide, part of the the Developer's Guide, is still in draft form. However, the following guidelines should be pretty close to current best practice. Any reviewer may approve and commit patches to the development "branch" (actually, the CVS trunk). This includes one's own patches. If you are submitting a patch that you expect to be controversial or that you expect other reviewers to take a strong interest in discussing, you should simply submit it, and note in the abstract that you intend to commit within a certain time frame. Eg, other reviewers will often give you this courtesy with respect to patches to Snufflopagus-related code. However, most reviewer patches will be committed at the time of submission. If you are approving a submission by a developer with commit privileges, who actually commits the patch is decided by mutual convenience of the submitter and the reviewer. Otherwise the reviewer must commit the patch. Approvals and commits are indicated by replying to the patch post, placing the module (21.5 for the trunk) and the action keywords in all caps (eg "APPROVE COMMIT 21.5") in the first line of the body, and some clear abbreviation in the Subject header. (The repetition is for the convenience of a patchbot we're planning to install.) The action keywords should start in column 1 and be the only text in the first line. If you believe a given patch should not be applied in anything like the submitted form, you should veto it. As with approves and commits, you send a reply to the patch to xemacs-patches, with the action keyword VETO. In the reply you must explain carefully why the patch is being vetoed. A veto is a very strong expression of disapproval, and can only be overridden by approvals from at least 3 other reviewers. Alternatively, you may delay application of a patch pending discussion or revision. The keyword QUERY seems to be the consensus for discussion. Some reviewers will use QUERY when asking for a specific revision, other will use REVISE for that case. You should send reply to _both_ xemacs-patches (for the benefit of patch-tracking) and to xemacs-beta, where discussion will occur. Please attempt to direct followups (eg, using Reply-To) to xemacs-beta. (We are planning a 'bot to handle this but it has not yet been implemented.) You may decide to submit an alternative patch. If the original patch should therefore not be applied, use the keyword SUPERSEDES. If at all possible, make explicit reference to the original patch via a message-id or an URL to the xemacs-patches archive. Patches for the stable (21.4) and gamma (currently no release is in process) branches must be approved by the maintainers (Vin for 21.4) before being committed. It is common practice when submitting or approving a patch for 21.5 to add the keyword RECOMMEND 21.4 to indicate the patch should also be applied to the stable branch. If the patch doesn't apply, you or the original submitter will be asked to work up a new one that does. In general, patches for Lisp packages may be recommended by any reviewer, but the current XEmacs Package Release Engineer prefers to do most commits himself. Also, many Lisp packages have external maintainers, in which case the external maintainer will be responsible for committing. (IIRC you are the external maintainer for Round-the-World-Tour.) Patches for Web site content may be approved and committed by any reviewer, but the webmaster, currently Adrian Aichner is most active. However, he encourages the rest of us to participate. Note that Adrian has created a validation target in the Web site make file; be sure to use it, and any other validation or link-setting tools you have that are available. Adrian coordinates changes to the website infrastructure. The Review Board is also the policy-making body for XEmacs. Discussion of policy and personnel matters takes place on the XEmacs Review mailing list, xemacs-review＠(a)xemacs.org. This list is closed subscription; you have already been subscribed. This list is archived at http://list-archive.xemacs.org/xemacs-review/. The archives are password-protected. The user is "ObRefFoo", the password is "Fooboref." Discussion of code and architecture on xemacs-review is strictly forbidden. Such discussion should be moved to xemacs-beta or xemacs-design as soon as you notice it. As a consequence, xemacs-review is a fairly low-traffic list. Policy issues come up on an ad-hoc basis. On policy matters we generally have operated on the basis of consensus. We don't currently have a conflict resolution mechanism, but there seems to be a growing amount of support for the Apache model, see http://dev.apache.org/guidelines/. Participation in policy discussions is up to the individual reviewer. Some people do as a matter of habit, some don't, and some pick their issues. Feel free to recruit new developers or package maintainers. In principle authorization to commit is granted by the review board, but in practice we have had no dissents. So in most cases, where the new developer has been an active participant on one or more of the development lists, or has specific expertise of value to XEmacs, you would simply recommend the new developer on xemacs-review. In the usual case of no opposition ("lazy consensus"), the next step is to get an SSH key, and ask one of the CVS maintainers (currently Adrian Aichner, Norbert Koch, and Stephen Turnbull, mail alias cvs-manager＠(a)xemacs.org) to add the key to the authorized_keys file for the xemacs account at SunSITE. Your aliases at xemacs.org have already been set up for some time. For your information, they are newbert.reviewer＠(a)xemacs.org newbie＠(a)general-conglobulation.com newbie＠(a)xemacs.org newbert.reviewer＠(a)xemacs.org newb.reviewer＠(a)xemacs.org newbert.reviewer＠(a)xemacs.org These are basically for your convenience; you can post from those addresses or whatever is convenient for you. In general we try to use our ＠(a)xemacs.org addresses for "official" announcements that go to xemacs-announce. Otherwise, it's a matter of personal taste. At present you are not pre-authorized to make announcements. If you need to make recurring announcements via xemacs-announce, contact the mailing list administrator at xemacs-mailmaint＠(a)xemacs.org. You already have commit privileges in the XEmacs repository at cvs.xemacs.org. If you have any trouble due to extensions of your permissions, let the CVS Managers know at cvs-manager＠(a)xemacs.org. The directions at http://www.xemacs.org/Develop/cvsaccess.html seem to be pretty clear. XEmacs uses facilities at Tux.org (mailing lists, FTP archive, and web site) and at SunSITE.dk (CVS repository, web site). There is also a web site mirror at SourceForge, but this is rarely of interest to anyone except the webmaster. If you need access to these resources, let me know (for Tux) or Adrian (for SunSITE). The administrators on both sites are very helpful within the constraints of their security policies, and if there is a reasonable need, they generally respond by providing access. If you have any questions, feel free to ask any of the reviewers directly (see http://www.xemacs.org/Develop/jobs.html) or post to xemacs-review, as seems appropriate. Stephen Turnbull <stephen＠(a)xemacs.org&gt; XEmacs Project Meta-Maintainer ＠end display ＠node Meta-Maintainer, Release Engineer, XEmacs Reviewer, The Work Roles ＠section Meta-Maintainer ＠cindex meta-maintainer The ＠dfn{meta-maintainer} is a reviewer who is responsible for general administration, including recruiting personnel to handle various chores required to keep the project running smoothly and handling correspondence for the XEmacs Review Board. The meta-maintainer generally also fills the role of ``Mr. XEmacs,'' the public representative of the project. For this reason the meta-maintainer should be an individual who has earned the respect and some power in the community, but the role does not provide any exceptional power itself. ＠node Release Engineer, Jobs List, Meta-Maintainer, The Work Roles ＠section Release Engineer ＠cindex release engineer ＠cindex release manager A ＠dfn{release engineer} (also called ＠dfn{release manager}) is responsible for the administrative aspects of releasing a distribution, including such things as ensuring that generated files are committed to CVS, tagging CVS, updating release documentation, creating and uploading tarballs, and making announcements. Release engineers are ＠emph{ex oficio} members of the XEmacs Review Board. ＠c #### MAKE A SEPARATE NODE CORRESPONDING TO jobs.html, AND FIGURE OUT ＠c HOW TO AUTOMAGICALLY UPDATE AND PUBLISH IT AS jobs.html. There are currently three XEmacs release engineers: Vin Shelton, for the stable XEmacs 21.4 branch; Norbert Koch, for the XEmacs package distribution, and Stephen Turnbull, for the development 21.5 branch (actually, the CVS trunk). ＠node Jobs List, , Release Engineer, The Work Roles ＠section Jobs List There are a number of auxiliary roles requiring special access to ＠value{PROJECT} resources, such as postmaster and webmaster. However, these roles do not differ substantially from similar roles in other projects or organizations, or explicitly control the daily workflow of the ＠value{PROJECT}, so definition will be postponed to the sections describing the roles in detail. Many of these roles are listed in the ＠uref{http://www.xemacs.org/Develop/jobs.html,Jobs List}. ＠node The Work Flow, XEmacs Resources on the Internet, The Work Roles, Top ＠chapter The Work Flow ＠c Created: stephen 2005-01-20 This section is a description of current best practices, rather than an attempt to define a standard. ＠cindex patch life cycle ＠cindex life cycle, patch ＠cindex workflow ＠heading The Life Cycle of a Patch ＠table ＠emph ＠item Get the sources. XEmacs is distributed with source, but CVS simplifies management of your improvements. ＠item Write low-profile code. Don't distract your users or colleagues from their work. Just make it easier. ＠item Test your changes. It's not done until you've proved it works the way you said it would. ＠item Add a ChangeLog entry. Tell us what you did. ＠item Create the patch. Dot the i's, cross the t's. Make sure that it's easy to add to the code base. ＠item Submit the patch. Compose the message so it's easy to find, easy to identify, easy to review, and easy to apply. ＠item Review the patch. The primary function of the ＠value{BOARD} is to help you improve your contributions. We aim for coherence and power in the interfaces, and maintainability in the implementation. ＠item Assign copyright. If you like; not required. ＠item Commit the patch. Who commits, how to commit, and when to commit. ＠item Dispute Resolution Any three developers will give you four ``best ways'' to do it. Now you have to pick one. ＠end table ＠menu * About Copyright Assignment:: * Scratching That Itch:: * Get the Sources:: * Write Low-Profile Code:: * Test Your Changes:: * Add a ChangeLog Entry:: * Create the Patch:: * Submit the Patch:: * Patch Review:: * Committing the Patch:: * Dispute Resolution:: ＠end menu ＠node About Copyright Assignment, Scratching That Itch, The Work Flow, The Work Flow ＠section About Copyright Assignment ＠cindex assignment of copyright ＠cindex copyright, assignment of Although XEmacs is a derivative of GNU Emacs, XEmacs is not a GNU project, nor does it require a copyright assignment to the FSF or anyone else. However, according to the FSF's legal advice, the best way to protect your investment in free software is to assign your copyright to the FSF (or other free software trust), which is required by its covenants of incorporation to actively defend free software it holds. You may also wish to respect the wishes of Richard Stallman, the first author and still major contributor to the development of Emacs. Finally, you may wish to support the FSF's advocacy of free software by assigning your copyright to the FSF. At the present time, the ＠value{PROJECT} neither advocates nor discourages this action; it's up to you. Also, be aware that 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. Get more information about procedures from the ＠email{emacs-devel＠(a)gnu.org,GNU Emacs developers' mailing list} or from ＠email{rms＠(a)gnu.org,Richard Stallman}. You may also wish to review ＠uref{http://www.gnu.org/prep/maintain.html,Information For Maintainers of GNU Software}, although it is not directly related to ＠value{PROJECT} procedures. ＠node Scratching That Itch, Get the Sources, About Copyright Assignment, The Work Flow ＠section Scratching That Itch ＠c 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 brilliant inspiration, a user request, or simply the mindless determination to keep up with the other One True Editor. ＠node Get the Sources, Write Low-Profile Code, Scratching That Itch, The Work Flow ＠section Get the Sources Maybe he's never worked on XEmacs before. In that case, he'll need to check out the ＠samp{xemacs} module from the CVS repository ＠ref{CVS Repository}. True, he may already have the whole package because he built from source after downloading a tarball. However, tarballs often lag current development by many months, and there's nothing that turns a maintainer off like a patch that doesn't apply because it was generated against an old version. Furthermore, the developer needs to keep track of the original file in order to generate a correct patch, which can be quite difficult if you go through several iterations woring on a complex issue. It's true that CVS has problems in advanced usage, but for these simple housekeeping tasks it works very well. Use CVS. ＠node Write Low-Profile Code, Test Your Changes, Get the Sources, The Work Flow ＠section Write Low-Profile Code ＠quotation As for the best leaders, the people do not notice their existence. ... When the best leader's work is done, the people say, ``We did it ourselves!'' ＠end quotation Software engineering is like leadership: true excellence means things ``just work,'' and nobody notices that you've intervened. Of course, nobody's perfect, and how you choose which imperfections you will and won't admit defines your style. However, we can derive some ideas about what kinds of submissions are more likely to be generally approved. With respect to software ＠emph{users}, we have the ＠strong{principle of least astonishment}. Users will have a more pleasant experience and work more efficiently if similar gestures in similar contexts produce analogous results. This applies to APIs, as well; if ＠code{forward-char} takes an optional signed integer argument and there is no ＠code{backward-char}, other developers will likely be rather annoyed if you define separate ＠code{forward-word} and ＠code{backward-word} functions, each taking a required non-negative integer. Of course interface design is a matter of judgment, but in cooperating with other developers there's a more technical standard that should also be applied: ＠strong{minimize your patches}. This principle extends to the degree of violating coding standards in situations like the following example. ＠example ＠{ /* new compound statement to enclose new_local_variable */ int new_local_variable = initializer (); ＠{ /* ＠strong{don't} reindent this brace */ /* or the following 25 lines, omitted here */ new_local_variable = iterator (new_local_variable); /* or the following 10 lines, also omitted */ ＠} /* nor the closing brace */ ＠} ＠end example This makes it easier to identify what has been changed, and equally important, what has not, when reading the patch. It also makes it more likely that two semantically independent patches will not interfere with each other. For similar reasons, ＠strong{follow the established coding standards} and resist the temptation to ``beautify'' code that is not directly relevant to your changes. If you follow these practices habitually, your patches will be more rapidly accepted with fewer requests for revision, and you will have more credibility when you do need to make an exception to the rule. ＠node Test Your Changes, Add a ChangeLog Entry, Write Low-Profile Code, The Work Flow ＠section Test Your Changes XEmacs provides a suite of regression tests which you can run with ＠code{make check}. Run them often, and definitely before you check in. Fixing one bug is hardly progress if it introduces another. Whenever you fix a bug, try to add a test for it to the test suite so it will be detected if it reappears, or if you fix fails on another platform. Whenever you add a feature, add new tests to validate its functionality. Some packages provide their own tests, which you should run before submitting changes to those packages. ＠node Add a ChangeLog Entry, Create the Patch, Test Your Changes, The Work Flow ＠section Add a ChangeLog Entry ＠c Created: stephen 2005-01-21 ＠strong{Needs revision!!} Add a log entry to ＠file{ChangeLog} file in the ancestor directory closest to each changed file. ＠menu * ChangeLogs:: * Log Messages:: ＠end menu ＠node ChangeLogs, Log Messages, Add a ChangeLog Entry, Add a ChangeLog Entry ＠subsection ChangeLogs ＠c Edited: stephen 2005-01-18 ＠strong{This section is pretty close to correct for XEmacs. Needs review.} ＠cindex ChangeLog Each module should have its own ＠file{ChangeLog}. Change logs are cool because they summarize all the changes in one place, and provide visibility to the changes to those who do not have access to the CVS repository. Here is an example ＠file{ChangeLog} entry: ＠example 2001-02-18 Bill Wohler <wohler＠(a)newt.com&gt; * Release mh-e-doc-1.3 for Emacs 21.1. * doc/mh-e.texi (Viewing): Added mh-header-display index entry. (Organizing,Customizing Reading): Added mh-kill-folder index entry. * doc/fixhtml (dohtml): Now part of main program now that program only fixes HTML files. Added -w and strict usage. (usage,dodvi,doinfo): Deleted. (fix_ref_links): Fixed a few uninitialized variables. Found a couple of variables and commands that weren't indexed. * doc/Makefile (EMACS): Point to $(TOP)/../remote/emacs. (XEmacs-DOCS): Added all relevant files. (ONLINE_DIR): Contains target directory for online files. (TEXI2HTMLFLAGS, MAKEINFOFLAGS): Added. (dist): Tags will have doc in them, so don't need to add. Release will now have all relevant files, rather than just mh-e.texi. (install-emacs): First ask user if he has updated and incorporated target emacs directory. (install-online): Implemented. (%.info,%.html,%.dvi,%.ps): Added. *doc/mh-e.texi (Viewing, Showing): Use new keymaps (closes SF #621632). ＠end example The first bullet shows the text that should be used when releasing a module. As usual, the string in parenthesis indicates the documentation section, Makefile variable or target, or program function or variable. If you do not use the Emacs ＠file{ChangeLog} commands such as ＠kbd{C-x 4 a} (＠code{add-change-log-entry-other-window}) which inserts this text for you (even from a diff!), please do follow its conventions. 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 The Emacs manual has full documentation on the ＠file{ChangeLog} commands. When you check in the change log, you do not need to supply any log message. ＠node Log Messages, , ChangeLogs, Add a ChangeLog Entry ＠subsection Log Messages ＠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.} ＠cindex log messages ＠cindex ChangeLog Log messages should be taken from ＠file{ChangeLog}. Given the ＠file{ChangeLog} in the previous section, here is what the log for ＠file{fixhtml} might look like: ＠example (dohtml): Now part of main program now that program only fixes HTML files. Added -w and strict usage. (usage,dodvi,doinfo): Deleted. (fix_ref_links): Fixed a few uninitialized variables. Found a couple of variables and commands that weren't indexed. ＠end example Note that the ＠code{*} and the filename have been removed, but this is not mandatory. However, if the same log message is used for multiple files, then the associated ＠code{*} and filenames will need to be present to separate the messages. ＠strong{Is this appropriate for XEmacs?} It is not necessary to add release information since that information will be encoded in the tags. At worst, setting the log information will be a cut and paste operation. At best, it will be a keystroke or two. In pcl-cvs, you can simply hit ＠kbd{C} (＠code{cvs-mode-commit-setup}) and you'll get a buffer in ＠code{log-edit-mode} initialized with the appropriate entries from the change log. Or, you can suck in the change log entries with ＠kbd{C-c C-a} (＠code{log-edit-insert-changelog}) if you use VC. I specify the following for ＠code{log-edit-hook} to make life easier: ＠example (defun my-log-edit-hook () "This assumes that you have already written a ChangeLog entry." (setq paragraph-start (concat paragraph-start "\\|(.*):")) (fill-region (point-min) (point-max))) ＠end example Log messages for files named ＠file{ChangeLog} may be empty. ＠node Create the Patch, Submit the Patch, Add a ChangeLog Entry, The Work Flow ＠section Create the Patch (The following lines describe the current patch creation standard for developers without commit access, committers, and reviewers alike. An optional alternative procedure for ＠emph{reviewers only} is likely to be adopted in first quarter 2005.) Patches should be created using a standard diff(1) such as provided by GNU diffutils, or implemented by CVS. A patch should be a ＠dfn{changeset}, that is, it should collect all of the related changes required to implement the improvement in a single file or message. The patch must be a context diff to avoid spurious commits. The ＠samp{diff -urN} format produced by GNU diff or recent CVS versions is strongly preferred (except for ＠file{ChangeLog}; see below). ＠strong{N.B.} If you use older diffs or CVS (eg, version CVS 1.10), please check for the presence of full relative paths in three places: the ＠samp{Index}, ＠samp{---}, and ＠samp{+++} lines. If the latter do not have the appropriate relative paths, patch(1) will invariably ＠emph{fail} to find the target file, and the application will fail. Any ＠file{ChangeLog} diffs must be removed from the main diff; because ＠file{ChangeLog} is changed in the same place (the beginning) with ＠emph{every} patch, context conflicts are extremely likely. On the contrary, since ＠file{ChangeLog} entries are essentially independent of each other, a ＠emph{contextless} ＠samp{diff -U 0} format patch at line 1, or plain text that can be easily cut and pasted, is the preferred format for the ＠file{ChangeLog} diff. These should be prepended to the changeset. Didier Verna's ＠file{patcher.el} is an excellent utility for creating patches for submission to XEmacs. It can also submit the patch and commit the changes to CVS as appropriate. ＠node Submit the Patch, Patch Review, Create the Patch, The Work Flow ＠section Submit the Patch ＠cindex patch submission ＠cindex submission, patch (The following lines describe the current patch submission procedure for developers without commit access, committers, and reviewers alike. An optional alternative procedure for ＠emph{reviewers only} is likely to be adopted in first quarter 2005.) Send the patch by email to ＠value{PATCHES-LIST}. The subject line should indicate the branch or CVS module in square brackets at the beginning of the field. Some developers like to include the keyword ＠samp{PATCH}; it is optional. After the square brackets, some mnemonic reference to the nature of the patch should be given. This might include the file that is patched or the bug issue being addressed: ＠example Subject: [21.5] src/regex.c: synch to recent GNU Emacs Subject: [PATCH web] Announce the release of XEmacs 21.4.6 Subject: [21.4 21.5] Fix mail truncation bug ＠end example The first line of the message may contain special keywords. The only ones normally used by non-reviewers are ＠samp{SUPERSEDES} and the module names. The keyword ＠samp{SUPERSEDES} ＠strong{must be used} if the patch is intended to be applied ＠emph{instead} of another addressing the same issue. In this case the message ＠strong{should} be constructed as a reply to the patch it supersedes (or to some followup to that patch). That is, the message header should contain a properly constructed ＠samp{References} header or an ＠samp{In-Reply-To} header or both. Optionally, if it is difficult to do this for some reason, an URL pointing to the thread in ＠value{PATCHES-LIST}'s archives, or (less desirable) the superseded patch's message ID, ＠strong{must} be included in the message body. It is best practice to include the module name(s) if any keywords are used. The module name(s) ＠strong{must} be present in the case of an original patch that applied to more than one module. For example, it is fairly likely that if the patch for mail truncation was generated against 21.4 it will fail to apply to 21.5. In that case, a new patch should be generated and the header and top of body of the submission message should resemble the following example: ＠example From: Newbert Developer <newbie＠(a)users.sourceforge.net&gt; To: xemacs-patches＠(a)xemacs.org Subject: [S21.5] Fix mail truncation bug References: <disappointed.21.5.maintainer＠(a)xemacs.org&gt; <original.patch.submission＠(a)users.sourceforge.net&gt; SUPERSEDES 21.5 Not needed for 21.4. This patch adapts the fix from <original.patch.submission＠(a)users.sourceforge.net&gt; to 21.5. src/ChangeLog: [etc, etc] ＠end example Didier Verna's ＠file{patcher.el} is an excellent utility for creating patches for submission to XEmacs. It can also submit the patch and commit the changes to CVS as appropriate. ＠menu * Proposed Optional Alternate Procedure for Reviewers:: ＠end menu ＠node Proposed Optional Alternate Procedure for Reviewers, , Submit the Patch, Submit the Patch ＠subsection Proposed Optional Alternate Procedure for Reviewers Patches that are self-approved by a reviewer, and are either expected to be non-controversial or are part of a project that has the general approval of the ＠value{BOARD}, may optionally omit the email submission. Instead, the responsible reviewer simply commits the patch, and the CVS commit-trigger will automatically generate and post the patch to ＠value{PATCHES-LIST}. This may be referred to as ＠dfn{implicit self-approval}. ＠strong{This procedure is not yet in effect, and the commit-trigger has not yet been implemented at the time of writing. (2005-01-20)} ＠node Patch Review, Committing the Patch, Submit the Patch, The Work Flow ＠section Patch Review ＠cindex patch approval ＠cindex approval, patch (The following lines describe the current patch submission procedure for developers without commit access and committers. Reviewers may optionally use ``commit-and-review,'' described later. Another optional alternative procedure for ＠emph{reviewers only} is likely to be adopted in first quarter 2005. Called ``implicit self-approval,'' it was described in the previous section.) After the patch has been distributed via ＠value{PATCHES-LIST} reviewers and other developers should review and test the patch. Discussion should continue on the same list. When a reviewer is satisfied that he understands the patch, he should post a ＠dfn{reviewer action}, which is a reply to the thread stating his formal decision. The currently defined reviewer actions are ＠table ＠samp ＠item APPROVE The patch is accepted, and will be committed by arrangement between the approving reviewer and the submitting developer. ＠item RECOMMEND The patch should be accepted, but it needs to be applied to code the reviewer doesn't have authority over (either a stable branch or a package with a designated maintainer). ＠item QUERY The reviewer likes the idea of the patch, but is delaying application subject to clear-cut revisions, or perhaps mere clarification of the intent or mechanism of the patch. ＠item REVISE The reviewer is demanding certain revisions, or the patch will be vetoed. May be obsolete; current practice seems to favor use of ＠strong{QUERY} both for required revisions and for further discussion, and there seems to be little need to distinguish these cases. ＠item VETO The reviewer thinks the patch is ill-conceived, and requires redesign before it will be acceptable. ＠end table There is currently some controversy on the ＠value{BOARD} about the meaning of a veto. Some reviewers interpret it as unalterable opposition that can only be settled with sabers or pistols, while others see it as a moratorium that might be, or might not be, permanent. In cases of the first three actions, the future path of the patch is clear. In the case of a ＠samp{VETO}, the veto may be overridden by three votes for ＠samp{APPROVE} among the reviewers. (It's not clear to me whether an override requires a majority, including at least three approvals, or a supermajority of two more approvals than vetos.) ＠menu * Commit-and-Review:: ＠end menu ＠node Commit-and-Review, , Patch Review, Patch Review ＠subsection Commit-and-Review A reviewer may self-approve his own submission. In this case, the reviewer may use ＠dfn{commit-and-review}, that is, submit, approve, and announce the commit in a single post to ＠value{PATCHES-LIST}. In cases of implicit self-approval or commit-and-review, other reviewers are expected to review in a timely fashion, and in the case of a ＠samp{QUERY} or ＠samp{VETO} post their action within a week. In the case of a ＠samp{VETO}, the patch must be reverted immediately, pending an override or withdrawal of the veto. ＠node Committing the Patch, Dispute Resolution, Patch Review, The Work Flow ＠section Committing the Patch ＠cindex patch, committing a ＠cindex committing a patch Once the patch has been approved, it should be checked in to CVS as soon as possible. The committer should prepare a commit message using the keyword ＠samp{COMMIT} as a reply to the approval message. (In the case of ＠emph{commit-and-review}, there is no way to reply, so this requirement is meaningless.) The CVS log message should refer unambiguously to the ＠samp{COMMIT} message, preferably via the RFC 2822 message ID. (The mailing list archives may lag up to 24 hours, so using an URL is infeasible.) ＠menu * Proposed Alternative Procedure:: ＠end menu ＠node Proposed Alternative Procedure, , Committing the Patch, Committing the Patch ＠subsection Proposed Alternative Procedure In the case of implicit self-approval, the CVS log message should describe the rationale for the patch, and list the affected modules and subdirectories in the tree. This should be enough to point reviewers to the relevant ChangeLog diffs, which will automatically be included. There will be no manual posts at all to ＠emph{xemacs-patches}, so there is no way to supply a message ID reference; that requirement is nullified. ＠strong{This procedure is not yet in effect, and the commit-trigger has not yet been implemented at the time of writing. (2005-01-20)} ＠node Dispute Resolution, , Committing the Patch, The Work Flow ＠section Dispute Resolution ＠cindex contesting vetos ＠cindex vetos, contesting ＠cindex protesting check-ins ＠cindex check-ins, protesting ＠cindex dispute resolution ＠strong{This is a first hack draft by ＠samp{stephen}. I have no idea whether it represents my own ``true'' opinion, let alone anyone else's.} There seems to be general agreement that ＠value{PROJECT} resources should be used to serve ``the users' needs'' first, before being used for developers' play---but there is disagreement over who those users are, and what their needs might be. There is general agreement that one of the advantages to working on XEmacs is the overall coherence of most of its architecture, and the dedication of the team to refactoring broken designs. However, the developers with fewer resources to devote feel overwhelmed by the ``code churn'' generated by the most prolific developers, and protest that memorizing global renamings and the like are rather frivolous ways to spend reviewer resources. These conflicts typically manifest as a dispute over some reviewer's use of a veto. Therefore I propose the following guidelines for use of vetos. ＠table ＠emph ＠item Only patches can be reviewed. And therefore, only patches can be vetoed. People can propose, purely for discussion, whatever they like. Such proposals ＠strong{may not} be vetoed. If somebody wants to submit a patch that's clearly against the sense of some member of the board, let them. It will be vetoed. If they resubmit a real revision, the reviewers must be allowed to consider it. Note how this deals with the ``use the ISO standard ＠samp{size_t} type for positive variables'' kind of issue. There's essentially only one way to write that patch. If it is vetoed and an attempt to override fails, the policy of the ＠value{BOARD} is clear. The patch should not be resubmitted until there's good reason to suppose the average stance of the board has shifted considerably. ＠item Reviewer decisions apply to the whole patch. Including vetos. This makes megapatches risky, obviously. It's up to the contributor to separate the parts; if something unacceptable is submitted as part of the megapatch, the reviewer should not be pressured to accept the whole, nor to do the surgery himself. If the megapatch is that important to the project, the board should be willing to override the veto. If the contributor can't get that support, he must split out the acceptable parts. ＠item Reasonable time constraints for reviewers. Except for global substitutions, megapatches are normally the result of weeks, even months, of secret work; reviewers should be allowed proportionate amounts of time to review them. If the work is done serially via commit-and-review, or on a branch, or (with approval of the Board) in ＠samp{#ifdef}s, then the reviewers get just as much time as the originator does, and they have no excuse for being ``surprised'' by the megamerge at the end. Note that the point of a branch here is ＠emph{not} incremental merging, it is to make progress on the megapatch public. So this costs only the trivial effort of committing your workspace to the branch every week or two. (Of course the big merge at the end will still be a lot of work, but that would be true if all the work was done in a local workspace and never committed to a branch.) ＠item Each resubmission of a patch restarts the clock. Reviewers need not work faster just because somebody has resubmitted the patch three times. If you submit a large patch with 52 major bugs, you had better be prepared to wait a year as it gets vetoed once a week, once for each bug. ＠item The submitter must revert an immediate commit if vetoed. If you take advantage of implicit self-approval, you have no arguments because you've short-circuited the review process. Had the patch gone through the full process, it never would have been applied---you're way ahead of the game as it is. Revert the patch. If the veto is abusive, the abusive reviewer should be disciplined---but showing that will take discussion, and that must happen after reversion. ＠item A veto after commit of a fully reviewed patch must be supported. If a patch goes through the full submit---review---approve---commit cycle, it may still be vetoed. However, in this case the burden of proof should be on the vetoer. The committer ＠emph{may} refuse to revert, and in that case, the vetoer needs two concurring vetos. This constitutes a blocking coalition of three---the patch must be reverted immediately, even if it seems likely that a vote of the board would back the commit. The patch can be reapplied after the vote. Some patches, ie, not submitted by reviewers, need the full submit---review---approve---commit process in any case. So if reviewers want some assurance that their patch won't be reverted after commit, they can take advantage of full review process (which still allows self-approval). ＠end table ＠node XEmacs Resources on the Internet, Support Requests, The Work Flow, Top ＠chapter XEmacs Resources on the Internet ＠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}. There should also be a node for the Emacs Wiki.} ＠cindex XEmacs Resources on the Internet ＠menu * Project Website:: * CVS Repository:: * comp.emacs.xemacs:: * xemacs-beta:: * xemacs-design:: * xemacs-patches:: * xemacs-mule:: * xemacs-winnt:: ＠end menu ＠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?} ＠cindex Project Website ＠cindex ＠value{XEMACSORG}, XEmacs Web space The ＠uref{http://www.xemacs.org/, XEmacs home page} contains a brief overview of the XEmacs project. This Web space also includes other internal documents, such as this one. ＠c #### this probably belongs elsewhere? this subtree is more user-oriented. To install your updates into the XEmacs Web space at ＠value{XEMACSORG}, simply check out the ＠file{xemacsweb} module ＠ref{CVS Repository}, make your changes, and check it in. The commit script takes care of generating the HTML and pushing the changes to the web servers' document spaces. ＠node CVS Repository, comp.emacs.xemacs, Project Website, XEmacs Resources on the Internet ＠section CVS Repository ＠c Edited: stephen 2005-01-18 ＠cindex CVS Repository ＠c #### update the specific links for convenience!! The ＠uref{http://cvs.xemacs.org/,CVS Repository} contains several modules. You can view the repository with ViewCVS from a link on repository's home page, and there is a link to an explanation of how to use CVS in the CVS Repository. ＠node comp.emacs.xemacs, xemacs-beta, CVS Repository, XEmacs Resources on the Internet ＠section The Usenet Newsgroup comp.emacs.xemacs ＠strong{Write me!} ＠node xemacs-beta, xemacs-design, comp.emacs.xemacs, XEmacs Resources on the Internet ＠section The xemacs-beta Mailing List ＠strong{Write me!} ＠node xemacs-design, xemacs-patches, xemacs-beta, XEmacs Resources on the Internet ＠section The xemacs-design Mailing List ＠strong{Write me!} ＠node xemacs-patches, xemacs-mule, xemacs-design, XEmacs Resources on the Internet ＠section The xemacs-patches Mailing List ＠strong{Write me!} ＠node xemacs-mule, xemacs-winnt, xemacs-patches, XEmacs Resources on the Internet ＠section The xemacs-mule Mailing List ＠strong{Write me!} ＠node xemacs-winnt, , xemacs-mule, XEmacs Resources on the Internet ＠section The xemacs-winnt Mailing List ＠strong{Write me!} ＠c ########################################################################## ＠c #### I haven't seriously worked on the following material. -- stephen #### ＠c ########################################################################## ＠node Support Requests, Bugs, XEmacs Resources on the Internet, Top ＠chapter Support Requests ＠cindex Support Requests Support requests are made to ＠value{BETA-LIST}. Developers should read the mailing list frequently, and after a period of inactivity, browse the ＠uref{http://list-archive.xemacs.org/xemacs-beta/,recent archives}. ＠node Bugs, Feature Requests, Support Requests, Top ＠chapter Bugs ＠c Edited: stephen 2005-01-18 ＠strong{We don't have a tracker. We should. Describe what it should look like here.} ＠cindex Bugs ＠cindex priority ＠cindex bugs, priority Bug reports, feature requests, and discussions that are expected to lead to bug reports or feature requests are created in ＠uref{https://sourceforge.net/bugs/?group_id=13357, Bugs}. Most bugs should be set to a priority of 5. ＠cindex bug-gnu-emacs ＠cindex Debian Developers should follow the ＠i{bug-gnu-emacs} mailing lists/newsgroup and move bug reports into Bugs if it has not been done already. Similarly, XEmacs bugs reported in other systems should be transfered to ＠value{XEMACSORG}. The bug may be cut and pasted into a new bug report, or a URL to the source of the original bug report may be all that appears in the bug report. A brief lifecycle of a bug proceeds something like this. A bug is entered. A developer ensures that the Category, Priority and Group are correct. The Group for an Open bug should be set to the version of software in which the bug was found, or CVS if it was found in the latest and greatest. The assignment of bugs in Bugs follows the honor system. If you see an open bug that you think you could handle, assign the bug to yourself. Bugs that remain open should be reviewed by a member of the ＠value{BOARD}, who should try to find a developer to work on the bug. If you fix a bug, set the resolution to Fixed and group to CVS. Please also assign the bug to yourself if you have not done so already, so you get credit in the ＠uref{https://sourceforge.net/tracker/reporting/?atid=113357&what=tech&span=&period=lifespan&group_id=13357#b, reports}. If a documentation change is not required, set the status to Closed. If a documentation change is required, set the category to Documentation, and assign the bug to the documentation tsar, leave the status Open, and set the priority to 3 to set it aside in listings sorted by priority. See ＠ref{File Releases} for a motivation of why this process is useful. The rest of this section describes the categories and groups that have been set up for the XEmacs project. ＠menu * Category:: * Status:: * Group:: * Resolution:: ＠end menu ＠node Category, Status, Bugs, Bugs ＠section Category ＠cindex category ＠cindex bug category Several categories have been created for the XEmacs project organized by function. They include ＠i{General}, ＠i{UI}, ＠i{MIME}, ＠i{Security}, ＠i{Documentation}, and ＠i{Contrib} ＠table ＠b ＠item General ＠cindex general bug category ＠cindex bug categories, general The ＠dfn{General} category is used for bugs that do not belong in any of the other categories. ＠item UI ＠cindex UI bug category ＠cindex bug categories, UI The ＠dfn{UI} category is used for bugs in the software that the user sees such as font-lock, key definitions, menus, and customization. ＠item MIME ＠cindex MIME bug category ＠cindex bug categories, MIME The ＠dfn{MIME} category is used for bugs that pertain to MIME. ＠item Security ＠cindex security bug category ＠cindex bug categories, security The ＠dfn{Security} category is used for bugs in the security arena. At present, XEmacs does not include any security code, so this category might be used for PGP interaction. ＠item Documentation ＠cindex documentation bug category ＠cindex bug categories, documentation The ＠dfn{Documentation} category is used for bugs in the documentation arena. In addition, if there are any code changes made as a result of a bug report or feature request that require changes to the documentation, the category of that issue should be set to Documentation after the bug has been fixed or the feature implemented. Assign the issue to ＠i{wohler} for editing and/or writing of the documentation, and set the priority to 3 to set the issue aside in listings sorted by priority. ＠item Contrib ＠cindex contrib bug category ＠cindex bug categories, contrib The ＠dfn{Contrib} category is used for all bugs in the contributed software. ＠end table ＠node Status, Group, Category, Bugs ＠section Status ＠cindex status ＠cindex bug status The bug ＠dfn{status} is divided into four sections: ＠i{Open}, ＠i{Closed}, ＠i{Deleted} and ＠i{Pending}. ＠table ＠b ＠item Open ＠cindex open bug status ＠cindex bug status, open When bugs are initially created, they are marked ＠dfn{Open}. ＠cindex discussing bugs ＠cindex bugs, discussing ＠cindex features, discussing The Bugs and Feature Requests sections are also used as a method to get the ball rolling among developers. They are used to register what we feel we should work on. For example, a developer may have questions about the way XEmacs handles MIME that we should discuss before we attempt to fix it: What do other people do? How should we attack this? That developer opens a bug report in the MIME category and a discussion ensues. Once the disposition of the issue is resolved, the bug is assigned to a developer. Later, when the bug is fixed, the bug can be closed. Discussion about entirely new features should be opened in the Feature Requests section (＠pxref{Feature Requests}) but otherwise handled in the same way. ＠item Closed ＠cindex closed bug status ＠cindex bug status, closed When all aspects of a bug have been fixed, including code and documentation, the bug is marked ＠dfn{Closed}. When setting the status to Closed, the group should be set to Fixed, Works For Me, Invalid, or Rejected. ＠item Pending ＠cindex pending bug status ＠cindex bug status, pending You can set the status to ＠dfn{Pending} if you are waiting for a response from the tracker item author. When the author responds, the status is automatically reset to that of Open. Otherwise, if the author doesn't respond within 14 days, then the item is given a status of Deleted. ＠item Deleted ＠cindex deleted bug status ＠cindex bug status, deleted If an items has been marked Pending, it will be marked ＠dfn{Deleted} if the author of the item does not respond within 14 days. ＠end table ＠node Group, Resolution, Status, Bugs ＠section Group ＠cindex group ＠cindex bug group The bug ＠dfn{group} contains several items. They include: ＠table ＠b ＠item None Bugs are initially filed in this group. ＠item CVS* Bugs in groups starting with CVS have either been found in the CVS version (in contrast to a released version) if the Status is Open, or they have been fixed and checked in if the Resolution is Fixed. After fixing a bug in a beta release, however, developers should not set the group to CVS but leave it in the group named for the beta release. Just be sure to mention the issue number in the ChangeLog so that it can be noted in the next release announcement. ＠item 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 Resolution, , Group, Bugs ＠section Resolution A bug can appear in various states: ＠table ＠b ＠item Accepted ＠cindex accepted resolution ＠cindex resolution, accepted The ＠dfn{Accepted} resolution means that QA has accepted the fix. Since we don't have a QA department, it is unlikely that this will be used in that fashion. Instead, it can be used to indicate that a developer feels that a feature request (that someone else posted) has merit. ＠item Duplicate ＠cindex duplicate resolution ＠cindex resolution, duplicate The ＠dfn{Duplicate} resolution means that this bug is a duplicate of another. The status may be set to Closed. Be sure to add a note which mentions the bug number that this bug is a duplicate of. If this bug has some good information in it, the URL to this bug should be added to the duplicate. ＠item Fixed ＠cindex fixed resolution ＠cindex resolution, fixed The ＠dfn{Fixed} group is used to indicate a bug or feature request that has been fixed. ＠item Invalid ＠cindex not a bug resolution ＠cindex invalid resolution ＠cindex resolution, not a bug ＠cindex resolution, invalid The ＠dfn{Invalid} resolution is used to indicate the problem is with the user. In other words, this is not a bug. See Works For Me. ＠item Later ＠cindex later resolution ＠cindex resolution, later The ＠dfn{Later} resolution is similar to the Postponed group, although it connotates a longer delay. ＠item Out of Date ＠cindex out of date resolution ＠cindex resolution, out of date The ＠dfn{Out of Date} resolution is similar to the term OBE (Overcome By Events). In other words, the bug has not been fixed, but the code has changed in ways that make it unnecessary to do so. ＠item Postponed ＠cindex postponed resolution ＠cindex resolution, postponed The ＠dfn{Postponed} resolution is similar to the Later group, although it connotates a lesser delay. ＠item Rejected ＠cindex rejected resolution ＠cindex resolution, rejected The ＠dfn{Rejected} resolution means that QA has rejected the fix. Since we don't have a QA department, it is unlikely that this will be used in that fashion. Instead, it can be used to indicate that a developer feels that a feature request does not have merit. ＠item Remind ＠cindex remind resolution ＠cindex resolution, remind The ＠dfn{Remind} resolution is similar to the Postponed and Later groups, although it connotates an even lesser delay. ＠item Wont Fix ＠cindex wont fix resolution ＠cindex resolution, wont fix The ＠dfn{Wont Fix} resolution means that the XEmacs developers acknowledge that the bug exists but are not going to fix it. Or the developers will not implement a feature request. There is probably a good reason for these things. ＠item Works For Me ＠cindex irreproducible resolution ＠cindex resolution, irreproducible ＠cindex works for me resolution ＠cindex resolution, works for me The ＠dfn{Works For Me} group is used to indicate a bug that cannot be reproduced (irreproducible) and therefore cannot be fixed. See Invalid. ＠end table ＠node Feature Requests, Patch Queue, Bugs, Top ＠chapter Feature Requests ＠c Edited: stephen 2005-01-18 ＠cindex Feature Requests 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 ＠c Edited: stephen 2005-01-18 ＠cindex Patch Queue Developers should check ＠value{PATCHES-LIST} occasionally for new patches and comment on the patch's usefulness and integrity. This will greatly help reviewers to review patches. Note that developers who are active in commenting on patches and bug reports are the main candidates when recruiting new reviewers. ＠c Legally speaking, patches that are less than 15 lines can usually be ＠c incorporated, although it is always best to try to incorporate them in ＠c a ``clean room'' environment. Do read ＠c ＠uref{http://www.gnu.org/prep/maintain_6.html#SEC6, Legally ＠c Significant Changes} for the details. ＠node File Releases, News, Patch Queue, Top ＠chapter File Releases ＠c Edited: stephen 2005-01-18 ＠strong{This node and all of its children need to be reviewed and adapted to the XEmacs process. One topic that ＠emph{must} be addressed is regenerating and checking in generated files.} ＠cindex File Releases This section contains information about how the XEmacs project releases software. In additional to making tarballs available, the software and documentation must be incorporated into Emacs and the online documentation must be updated. ＠menu * Release Schedule:: * Release Prerequisites:: * Updating NEWS:: * Updating README:: * Updating Version Number:: * Updating ChangeLogs:: * Tagging Releases:: * Creating Tarballs:: * Creating ＠value{XEMACSORG} Releases:: * Updating the Tracker:: * Announce the Release:: * Updating the Emacs Repository:: * Updating the Debian Package:: * Updating the XEmacs Package:: * Updating the Online Documentation:: * Updating the Free Software Directories:: * After the Release:: ＠end menu ＠node Release Schedule, Release Prerequisites, File Releases, File Releases ＠section Release Schedule ＠c Edited: stephen 2005-01-18 ＠strong{Totally bogus for XEmacs historical practice, probably totally unrealistic as future policy.} Here is a suggested schedule for a release: ＠quotation ＠multitable ＠columnfractions .3 .3 .4 ＠item ＠strong{Time} ＠tab ＠strong{Milestone} ＠tab ＠strong{Description} ＠item T-4 weeks ＠tab Soft Freeze ＠tab All P7 and higher features must be committed. P6 features should be committed. Any other new features destined for the release must be committed no later than this time. However, note that it is advisable not to release new user-visible features this late in the game. It is better to add new features at the beginning of a release cycle to allow for suitable usability testing. Testing commences. ＠item T-3 weeks ＠tab Hard Freeze ＠tab All P7 and higher bug fixes must be committed. P6 bug fixes should be committed. Testing continues. ＠item T-2 weeks ＠tab Beta 1 ＠tab Cut beta release. Upload to ＠value{XEMACSORG}. ＠item T-1 weeks ＠tab Beta 2 ＠tab Cut beta release. Upload to ＠value{XEMACSORG}. ＠item T-0 weeks ＠tab Release! ＠tab Cut release. Upload to ＠value{XEMACSORG}. ＠end multitable ＠end quotation Once a release date has been determined, the milestones leading up to that release should be posted as a news item (＠pxref{News}). With frequent minor releases, omit the beta releases and pre-announcement. ＠node Release Prerequisites, Updating NEWS, Release Schedule, File Releases ＠section Release Prerequisites ＠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}. Next, check for Emacs changes to XEmacs as described in section ＠ref{Updating the Emacs Repository}. ＠node Updating NEWS, Updating README, Release Prerequisites, File Releases ＠section Updating NEWS ＠cindex NEWS ＠cindex news ＠cindex src ＠cindex Debian When the ＠code{src} module is released (＠pxref{CVS Repository}), the file ＠file{NEWS} needs to be updated. Separate the old news with the new with a ＠kbd{C-l} and follow the existing format for documenting user-visible changes only including New Features, New Variables, and Bug Fixes. List ＠value{XEMACSORG} issues as ＠code{(closes SF #123456)}, as well as third-party issues such as ＠code{(closes SF #123456, Debian #123456)}. In order to find what is appropriate for ＠file{NEWS}, several things can be done. ＠enumerate ＠item Go to ＠uref{https://sourceforge.net/bugs/?group_id=13357, Bugs} and search for all bugs whose status is Closed and group is CVS (no documentation update needed) or status is Open, group is CVS, and category is Documentation (documentation update needed but not finished). ＠item Repeat for ＠uref{https://sourceforge.net/tracker/?atid=363357&group_id=13357, Feature Requests}. ＠item ＠cindex release-utils Run the ＠code{release-utils --variable-changes ＠var{previous-tag}} to produce a list of new and deleted variables suitable for inclusion in ＠file{NEWS}. ＠item Run ＠kbd{C-h m} in MH Folder and MH Letter modes in both the new and old versions to show the key binding changes. ＠item Search for ＠code{[0-9][0-9][0-9][0-9][0-9][0-9]} in the ＠file{ChangeLog} to get a list of SF numbers. ＠item Use the ChangeLog. ＠end enumerate The previous steps usually catch most items. To use a finer sieve, use the following commands. These assume that the last version of 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 Updating README, Updating Version Number, Updating NEWS, File Releases ＠section Updating README ＠cindex README Ensure that the target Emacs version is correct, as well as the supported Emacs versions. Update the version number in various places in the INSTALL section. See section ＠ref{Updating ChangeLogs} before checking in this file. ＠node Updating Version Number, Updating ChangeLogs, Updating README, File Releases ＠section Updating Version Number ＠set VERSIONFILE ＠file{$＠{srcdir(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. The first in a series of stable releases is a special case, because it involves creation of a new stable branch and affects numbering of the trunk as well. In the new stable branch, ＠value{VERSIONFILE} must assign the empty value to ＠samp{emacs_is_beta}. The value ``0'' is assigned to ＠samp{emacs_beta_version}. The next ＠emph{even} number (which is ``0'' in the case that ＠samp{emacs_major_version} is bumped) is assigned to ＠samp{emacs_minor_version}, and ＠samp{emacs_major_version} is bumped if that was authorized by the XEmacs Review Board. The codename ＠samp{xemacs_codename} is assigned at the discretion of the stable release engineer. At the same time, a new release of the trunk, identical except for version information, is made. ＠emph{The version information is the same as the stable release}, except that ＠samp{emacs_minor_version} is bumped to the next ＠emph{odd} integer, and ＠samp{xemacs_codename} is assigned at the discretion of the beta release engineer. Release engineers usually choose a theme for codenames and make the proposed series available in a file. The name ＠samp{emacs_beta_version} probably could have been more aptly chosen, but it is a historical relic of the fact that it was first used in the beta series, then adopted in the stable branch. The name is not user-visible; the value of this variable is called the patch level in stable branch documentation. ＠strong{N.B.} Release engineers should avoid disturbing the order of variables in ＠value{VERSIONFILE}. The variables ＠samp{emacs_kit_version}, ＠samp{infodock_major_version}, ＠samp{infodock_minor_version}, and ＠samp{infodock_build_version} are used for version information of various non-＠value{PROJECT} releases, and should be ignored. Both of these features are unclean, but users' auxiliary tools (and some tools distributed by the ＠value{PROJECT}, including ＠file{build.el} and ＠file{build-report.el} in some releases) often depend on the syntax of this file to work correctly. In beta releases, there is an optional variable ＠samp{xemacs_extra_name} which is a string that is appended to the version string. It is currently automatically updated, and used to identify the date of a CVS checkout. Except in cases involving creation of a new stable branch, update of the version information simply requires bumping ＠samp{emacs_beta_version} and assignment of a new ＠samp{xemacs_codename}. ＠node Updating ChangeLogs, Tagging Releases, Updating Version Number, File Releases ＠section Updating ChangeLogs ＠cindex ChangeLog Add a ChangeLog entry to ＠emph{every} ChangeLog in the tree, marking the release. The text of the first line should match this regexp: ＠example XEmacs \d+\(?:\.\d+\)+\(?:-b\d+\)?\(?:"\(\w\|\s-\)+"\)? is released ＠end example ＠node Tagging Releases, Creating Tarballs, Updating ChangeLogs, File Releases ＠section Tagging Releases ＠cindex tags ＠cindex CVS, tag ＠cindex version numbers It is critical that a snapshot of the software is created each time the software is released. In CVS, this is performed with tags. Every series of stable releases must have a branch tag of the form ＠i{release-M-N}. The trunk has no branch tag. Every release must have a fixed tag of the form ＠i{release-M-N-B}, where ＠var{M} is the major number, ＠var{N} is the minor number, and ＠var{B} is the beta release or patch number. A hyphen is used since one cannot use dots in CVS tag names. The stable release branch tag doubles as a tag of the most recent release. While this is not quite true during the process of accumulating patches to the branch, due to the conservative nature of that process it seems very unlikely to cause trouble. Since the trunk has no tag, and many beta testers would prefer to avoid checking out in the middle of a series of related check-ins, a fixed tag of the form ＠i{release-M-N-current-beta} is used to identify the current beta release. It is updated by a command like ＠samp{cvs rtag -F -r release-M-N-B release-M-N-current-beta}. The packages have independent release schedules, determined by the XEmacs package maintainer and the XEmacs Package Release Engineer. ＠node Creating Tarballs, Creating ＠value{XEMACSORG} Releases, Tagging Releases, File Releases ＠section Creating Tarballs ＠cindex Creating Tarballs ＠cindex CVS Repository ＠cindex modules ＠cindex CVS, modules ＠cindex tarballs, naming The modules in the CVS Repository (＠pxref{CVS Repository}) map to the distribution tarballs as follows: ＠quotation ＠multitable ＠columnfractions .4 .6 ＠item ＠strong{Module} ＠tab ＠strong{Tarball} ＠item src ＠tab mh-e-M.N.tgz ＠item doc ＠tab mh-e-doc-M.N.tgz ＠item contrib ＠tab mh-e-contrib-M.N.tgz ＠end multitable ＠end quotation ＠cindex tarballs, making ＠cindex tarballs, naming ＠cindex tags ＠cindex CVS, tags ＠cindex Makefile targets, dist ＠cindex version numbers The tarballs listed in the table above are built as follows: ＠itemize ＠cindex CVS, co ＠item If ＠var{module} has not been checked out already, check it out: ＠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 ＠item If ＠var{module} has been checked out already, set the sticky tag for the release: ＠example cvs update -r ＠var{release} ＠end example ＠item Build the tarball. ＠example cd ＠var{module} make dist ＠end example ＠end itemize 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. ＠node Creating ＠value{XEMACSORG} Releases, Updating the Tracker, Creating Tarballs, File Releases ＠section Creating ＠value{XEMACSORG} Releases ＠cindex Creating ＠value{XEMACSORG} Releases ＠cindex releases ＠cindex tarballs, making 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. ＠node Announce the Release, Updating the Emacs Repository, Updating the Tracker, File Releases ＠section Announce the Release ＠cindex Announce the Release Now that the release is ready for download, announce it as described in ＠xref{News}. ＠node Updating the Emacs Repository, Updating the Debian Package, Announce the Release, File Releases ＠section Updating the Emacs Repository ＠c Edited: stephen 2005-01-19 ＠strong{Needs review. Although on the face of it this obviously has nothing to do with XEmacs, in fact there are probably hints here for XEmacs release engineers.} ＠cindex Updating the Emacs Repository ＠cindex Emacs, updating The Emacs repository is updated by the project admin. Other developers may skip this section. ＠cindex gnu.org ＠cindex CVS Emacs Repository ＠cindex Emacs CVS Repository ＠cindex Savannah The project admin must have an account on the ＠i{gnu.org} machines, and must also be given access to the Emacs CVS repository. This can be accomplished by following these steps: ＠table ＠emph ＠item Obtain a ＠uref{https://savannah.gnu.org/account/register.php, Savannah login}. ＠item Become an Emacs developer by contacting one of the admins listed on the ＠uref{https://savannah.gnu.org/projects/emacs/, Emacs main page}. ＠item Follow the instructions given in ＠uref{https://savannah.gnu.org/cvs/?group=emacs, the CVS instructions}. ＠end table ＠cindex emacs-devel ＠cindex mailing lists, emacs-devel ＠cindex mailman The project admin must also join the ＠i{emacs-devel} mailing list. Send a note to ＠i{emacs-devel-request＠(a)gnu.org} or use the ＠uref{http://mail.gnu.org/mailman/listinfo/emacs-devel, Mailman interface} to subscribe. This procedure must be performed before any changes have been made to the XEmacs source since the release. This can be easily accomplished in by checking out the module with a sticky tag and should be done in any case. ＠cindex CVS, co First, check out the Emacs source: ＠example cvs -d $USER＠＠savannah.gnu.org:/cvsroot/emacs co emacs ＠end example If the Emacs source has already been checked out, ensure that the XEmacs source is not locally modified. This is essential for the next step to proceed accurately. If the install-emacs step described below had been performed during testing leading up to the release, remove the modified XEmacs files and run ＠code{cvs update} again. ＠cindex import-emacs ＠cindex Makefile targets, import-emacs Next, ensure that there have not been any upstream changes to either the source or documentation. If so, the changes will need to be imported into the ＠file{src} and ＠file{doc} modules. This is done by running: ＠example make import-emacs ＠end example ＠cindex EMACS_HOME ＠cindex environment variables, EMACS_HOME ＠cindex variables, EMACS_HOME ＠cindex install-emacs ＠cindex Makefile targets, install-emacs Then install the sources with: ＠example cd src make install-emacs ＠end example The ＠code{install-emacs} target copies the lisp files to ＠file{$EMACS_HOME/lisp/mh-e} and copies ＠file{NEWS} to ＠file{$EMACS_HOME/etc}. ＠cindex EMACS_HOME ＠cindex environment variables, EMACS_HOME ＠cindex variables, EMACS_HOME ＠cindex install-emacs ＠cindex Makefile targets, install-emacs ＠cindex ChangeLog Next, install the documentation with: ＠example cd doc make install-emacs ＠end example This target copies ＠file{mh-e.texi} to ＠file{$EMACS_HOME/man}. Update ＠code{$EMACS_HOME/etc/ChangeLog} and ＠code{$EMACS_HOME/man/ChangeLog}. Simply cite the XEmacs release. For example: ＠example * NEWS, NEWS: Upgraded to XEmacs version 6.1. ＠end example and ＠example * mh-e.texi: Upgraded to XEmacs documentation version 1.3. ＠end example Update ＠code{$EMACS_HOME/etc/NEWS} by adding text similar to the following: ＠example * Changes in Emacs 21.4 ** XEmacs changes. Upgraded to XEmacs version 6.1. Upgraded to XEmacs manual version 1.3. See NEWS for details. ＠end example It's possible that the update occurs before Emacs had been released with a previous version of XEmacs; in this case, simply bump the version number in the text above rather than add an entire new stanza. Then check in the files like this: ＠example cvs ci -m"Upgraded to XEmacs version 6.1. See etc/NEWS and lisp/mh-e/ChangeLog for details." ＠end example ＠cindex emacs-devel ＠cindex mailing lists, emacs-devel Send a note to ＠i{emacs-devel＠(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: ＠example XEmacs 7.4.4 checked in ＠end example The first paragraph should include the description on the ＠uref{https://sourceforge.net/projects/mh-e/, Summary} page, and the text: ＠example Read on for more details. ＠end example The second paragraph should contain: ＠example Project home page at: http://mh-e.sourceforge.net/. ＠end example Finally, append the release notes. If only the manual is updated, then the announcement should read closer to the one used in the ＠value{XEMACSORG} news item. After checking XEmacs into Emacs, run ＠code{make import-emacs} a second time to put the new code on the Emacs branch. This makes it possible to detect changes to XEmacs that an Emacs developer may make later. ＠node Updating the Debian Package, Updating the XEmacs Package, Updating the Emacs Repository, File Releases ＠section Updating the Debian Package ＠cindex Updating the Debian Package ＠cindex Debian Package, Updating ＠cindex Debian 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. ＠example apt-get install build-essential fakeroot debhelper texinfo dpkg-dev-el ＠end example Run the following commands from the top of the CVS tree to clean up the tree of backup files and make a source tar file: ＠example rm `find . -name "*~"` debian/rules source ＠end example This will make a new file such as ＠code{mh-e_7.0.orig.tar.gz}. Unpack it in a working directory and step into its top directory. Edit the first line of the file ＠file{debian/changelog} to change the version number between parentheses to something appropriate (e.g. ＠code{7.0.+cvs-0}), or add another entry to the changelog and edit the version number. If you installed the package ＠code{dpkg-dev-el} above, simply do ＠kbd{C-c C-v} to insert this block and ＠kbd{C-c C-f} to finalise the entry when done editing the version number. You can then create a Debian package by running: ＠example fakeroot debian/rules binary ＠end example This creates ＠file{../mh-e_7.0.+cvs-0_all.deb} which can be installed using standard Debian package management: ＠example dpkg -i ../mh-e_7.0.+cvs-0_all.deb ＠end example ＠node Updating the XEmacs Package, Updating the Online Documentation, Updating the Debian Package, File Releases ＠section Updating the XEmacs Package ＠cindex Updating the XEmacs Package ＠cindex XEmacs Package, Updating ＠cindex XEmacs This task is the duty of XXX <＠i{XXX}>. It may be useful to others to want to make an unofficial package of the CVS tree. The rest of this section needs to be completed. ＠node Updating the Online Documentation, Updating the Free Software Directories, Updating the XEmacs Package, File Releases ＠section Updating the Online Documentation ＠c Edited: stephen 2005-01-19 ＠strong{Adrian, please review.} ＠cindex Updating the Online Documentation ＠cindex online documentation, updating ＠cindex documentation, updating online ＠cindex CVS, update The entire XEmacs web site is kept in CVS, and automatically rebuilt by the commit trigger. Thus, the basic procedure is similar to working on XEmacs source code. ＠enumerate ＠item Check out the ＠samp{xemacsweb} module. ＠item Make the needed changes. ＠item Update the ChangeLog(s). ＠item Test the changes with ＠code{make} to ensure that all ＠file{genpage} commands are correct. Then use ＠code{make validate} to check that the produced HTML is reasonably correct. ＠item Commit the workspace. ＠end enumerate The XEmacs online documentation is mostly written in the ＠file{genpage} language, which ensures a consistent interface for internal links via special commands processed by the ＠code{genpage} script, and a consistent overall format enforced by use of template files. Some of the material, such as the online versions of the ＠emph{XEmacs User's Guide} is generated directly from Texinfo, and checked in to CVS as HTML rather than ＠file{genpage} source. The validator used by ＠code{make validate} is based on the PSGML package. It is not perfect, but it is more convenient than the more accurate online validators provided by the W3C and others. The webmaster should use the online validators and link checkers regularly. ＠node Updating the Free Software Directories, After the Release, Updating the Online Documentation, File Releases ＠section Updating the Free Software Directories ＠c Edited: stephen 2005-01-18 ＠strong{Add FreshMeat, at least.} Update the ＠i{source-tarball} and ＠i{version} fields in the FSF/UNESCO Free Software Directory (＠pxref{Free Software Directories}), as well as the ＠i{touched} field. Update any other fields as necessary, including the ＠i{updated} field. ＠node After the Release, , Updating the Free Software Directories, File Releases ＠section After the Release ＠cindex After the Release After the release is complete, add the string ＠code{+cvs} to the version number. ＠xref{Updating Version Number}. Then, define the next release. Each developer goes through the bugs and feature requests and chooses a month's worth of work for him to do. For each selected item, he increases the priority to 7 and assigns the task to himself. Another guideline for release size is that releases should only include 7 +/- 2 new features or bug fixes. The first month should be full of fervent activity. Development should slow down in the second month while the new features are fine-tuned. The third month is devoted to the release. ＠xref{Release Schedule}. It is acceptable and often desirable to shorten each step in this cycle in order to keep the number of release note bullet items to 7 +/- 2, but in order to keep the releases fresh, it's probably not a good idea to lengthen the process. If a new bug or feature arises that a developer wants to work on, the developer sets the priority of that item to 7 and resets the priority of one of his other items back to 5. This keeps the release from growing without bound. The motivation for this schedule is to keep the iteration cycle short, to keep from adding new features just before a release, and from the user's point of view, to increase the timeliness and quality of releases. It also limits the scope of the release, and makes it clear when we're done. ＠node News, Surveys, File Releases, Top ＠chapter News ＠c Edited: stephen 2005-01-18 ＠strong{Needs review.} ＠cindex News ＠cindex xemacs-announce ＠cindex mailing lists, xemacs-announce ＠cindex emacs-devel ＠cindex mailing lists, emacs-devel Announcements about new releases are submitted ＠uref{http://sourceforge.net/news/?group_id=13357, at ＠value{XEMACSORG}}, to ＠i{xemacs-announce＠(a)lists.sourceforge.net}, and to ＠i{emacs-devel＠(a)gnu.org}. The ＠i{emacs-devel} list should not be used for contrib releases, however. The document ＠uref{https://sourceforge.net/docman/display_doc.php?docid=12834&group_id=1, Using Project News with Step-by-Step Instructions} is helpful when composing your news item. In all cases, use the following template for the subject: ＠example XEmacs m.n.p released XEmacs contributed software m.n.p released XEmacs manual m.n.p released ＠end example As only the first paragraph is shown on the ＠value{XEMACSORG} front page, it should be written wisely. Emulate the look and feel of previous news postings. The first sentence should be the same as the first sentence in the description on the ＠uref{https://sourceforge.net/projects/mh-e/, Summary} page. The following sentences are typically copied from the first paragraph of the release notes and should briefly describe the benefit of the release or otherwise entice the reader to read further. The contrib and doc releases, which do not have release notes, should include a sentence or two which summarizes the release. The last sentence of the first paragraph should read: ＠example Read on for more details. ＠end example Use the following for the second paragraph: ＠example Project home page at: http://mh-e.sourceforge.net/. ＠end example Finally, include the release notes from ＠file{NEWS}. Because the introductory paragraph was already used, include the release notes starting with the ``New Features'' item. To avoid ugly wrapping, first make every paragraph one line by copying the release notes into a scratch buffer, setting the fill column to some very large number, and running ＠code{fill-region}. For contrib and doc releases, use the ChangeLog entries since the last release. Note that your news posting may be shown on the ＠value{XEMACSORG} front page, so discretion is advised. The announcement that is sent to the ＠i{xemacs-announce} mailing list doesn't have the same first-paragraph restrictions as does the ＠value{XEMACSORG} news item. Therefore, the announcement should contain the text: ＠example Project home page at: http://www.xemacs.org/. ＠end example followed by the release notes. However, the announcement for contrib and doc releases, which lack release notes, should be closer to the news item. The Emacs announcement is described in ＠ref{Updating the Emacs Repository}. ＠node Surveys, Free Software Directories, News, Top ＠chapter Surveys ＠c Edited: stephen 2005-01-18 ＠strong{Interesting. Should we do this, maybe?} ＠cindex Surveys The project admin may create ＠uref{https://sourceforge.net/survey/?group_id=13357, Surveys}. The interface is backwards. First you create questions and note the question IDs. Then you create a survey and list the question IDs. ＠node Free Software Directories, Copying, Surveys, Top ＠chapter Free Software Directories ＠cindex FSF/UNESCO Free Software Directory ＠cindex Free Software Directories ＠cindex Software Directories The ＠uref{http://www.gnu.org/directory/, FSF/UNESCO Free Software Directory} contains a description of all of the free software, including ＠uref{http://www.gnu.org/directory/XEmacs.html, XEmacs}. It must be updated when there is a release of XEmacs, or when a significant new feature has been added which should be advertised. This entry is the master for the short and long descriptions of XEmacs in various places. These items should be updated each time the master entry is modified. In order to update the entry, first ＠uref{http://savannah.gnu.org/cvs/?group_id=32, check out} the directory via anonymous CVS: ＠example cvs -d:pserver:anoncvs＠＠subversions.gnu.org:/cvsroot/directory login cvs -z3 -d:pserver:anoncvs＠＠subversions.gnu.org:/cvsroot/directory co directory ＠end example or CVS via SSH: ＠example cvs -z3 -d <membername>＠＠subversions.gnu.org:/cvsroot/directory co directory ＠end example Then make the desired changes to ＠file{XEmacs.txt}. Next, update the ＠i{touched} field. If the changes were significant enough to be announced, update the ＠i{updated} field as well. For a description of each field, see the ＠uref{http://www.gnu.org/gnulist/README, README}. Send the patch to ＠i{bug-directory＠(a)gnu.org}. For more information, see the ＠uref{http://www.gnu.org/help/directory.html, instructions}. Finally, if any changes were made to the short or long descriptions, it is likely that the following will have to be updated: the ＠value{XEMACSORG} XEmacs project description (see ＠uref{https://sourceforge.net/project/admin/editgroupinfo.php?group_id=13357, Editing the ＠value{XEMACSORG} Project Description}), the top-level ＠file{index.php} file in the Project Website (＠pxref{Project Website}), the ＠file{control} file in the Debian package (＠pxref{Updating the Debian Package}), and the XEmacs package (＠pxref{Updating the XEmacs Package}). ＠c #### Nuke this, but check whether the topics below need discussion. ＠c ＠node Miscellaneous Topics, Copying, Free Software Directories, Top ＠c ＠chapter Miscellaneous Topics ＠c ＠c This section contains a few items that should probably be deleted, but ＠c are kept for completeness. ＠c ＠c ＠menu ＠c * Task Manager:: ＠c * DocManager:: ＠c * Public Forums:: ＠c * Anonymous FTP Space:: ＠c ＠end menu ＠node Copying, Index, Free Software Directories, Top ＠appendix GNU GENERAL PUBLIC LICENSE ＠center Version 2, June 1991 ＠display Copyright ＠copyright{} 1989, 1991 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. ＠end display ＠appendixsec Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software---to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. The precise terms and conditions for copying, distribution and modification follow. ＠iftex ＠appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION ＠end iftex ＠ifinfo ＠center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION ＠end ifinfo ＠enumerate 0 ＠item This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The ``Program,'' below, refers to any such program or work, and a ``work based on the Program'' means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term ``modification.'') Each licensee is addressed as ``you.'' Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. ＠item You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. ＠item You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: ＠enumerate a ＠item You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. ＠item You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. ＠item If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) ＠end enumerate These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. ＠item You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: ＠enumerate a ＠item Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, ＠item Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, ＠item Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) ＠end enumerate The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. ＠item You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. ＠item You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. ＠item Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. ＠item If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. ＠item If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. ＠item The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and ``any later version,'' you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. ＠item If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. ＠iftex ＠heading NO WARRANTY ＠end iftex ＠ifinfo ＠center NO WARRANTY ＠end ifinfo ＠item BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW＠. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE＠. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU＠. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. ＠item IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. ＠end enumerate ＠iftex ＠heading END OF TERMS AND CONDITIONS ＠end iftex ＠ifinfo ＠center END OF TERMS AND CONDITIONS ＠end ifinfo ＠page ＠appendixsec How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the ``copyright'' line and a pointer to where the full notice is found. ＠smallexample ＠var{one line to give the program's name and an idea of what it does.} Copyright (C) 19＠var{yy} ＠var{name of author} This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE＠. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. ＠end smallexample Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: ＠smallexample Gnomovision version 69, Copyright (C) 20＠var{yy} ＠var{name of author} Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. ＠end smallexample The hypothetical commands ＠samp{show w} and ＠samp{show c} should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than ＠samp{show w} and ＠samp{show c}; they could even be mouse-clicks or menu items---whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a ``copyright disclaimer'' for the program, if necessary. Here is a sample; alter the names: ＠smallexample ＠group Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. ＠var{signature of Ty Coon}, 1 April 1989 Ty Coon, President of Vice ＠end group ＠end smallexample This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License. ＠node Index, , Copying, Top ＠unnumbered Index ＠printindex cp ＠bye