[AC pkgs] Update xemacs-devguide.texi

APPROVE COMMIT general-docs Norbert: Not crucial, but a release would be appreciated as the previous version was totally Mercurial-unware! Index: ChangeLog =================================================================== RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/general-docs/ChangeLog,v retrieving revision 1.22 diff -u -r1.22 ChangeLog --- ChangeLog 13 May 2007 12:23:58 -0000 1.22 +++ ChangeLog 24 Feb 2009 09:32:02 -0000 ＠＠ -0,0 +1,6 ＠＠ +2009-02-24 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * texi/xemacs/xemacs-devguide.texi: + Make various changes to adjust for current reality (especially, + describe the Mercurial repository briefly). + Index: texi/xemacs/xemacs-devguide.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/general-docs/texi/xemacs/xemacs-devguide.texi,v retrieving revision 1.6 diff -u -r1.6 xemacs-devguide.texi --- texi/xemacs/xemacs-devguide.texi 12 May 2007 17:04:26 -0000 1.6 +++ texi/xemacs/xemacs-devguide.texi 24 Feb 2009 09:32:04 -0000 ＠＠ -10,9 +10,9 ＠＠ ＠c Developer's Guide variables. ＠set DEVGUIDE ＠cite{XEmacs Developer's Guide} -＠set EDITION 0.6 -＠set UPDATED 2007-02-17 -＠set UPDATE-MONTH February, 2007 +＠set EDITION 0.7 +＠set UPDATED 2009-02-24 +＠set UPDATE-MONTH February, 2009 ＠c Other variables. ＠set XEMACSORG XEmacs.ORG ＠＠ -164,6 +164,7 ＠＠ XEmacs Resources on the Internet * Project Website:: +* Mercurial Repository:: * CVS Repository:: * comp.emacs.xemacs:: * xemacs-beta:: ＠＠ -237,9 +238,9 ＠＠ 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. +effectively. First, it describes the philosophy of the development team. +A section for each resource in the ＠value{PROJECT} that +developers may want to use or need to change follows. In other words, this is the single sheet of music that all the XEmacs developers are playing. ＠＠ -322,8 +323,8 ＠＠ A change in the major version number indicates a pervasive change affecting all users. For example, the introduction of Mule in version -20, the extensive user of the package system in 21, and Unicode support -in 22. A change in the minor version number reflects addition of +20, the extensive use of the package system in 21, and Unicode support +is planned for 22. A change in the minor version number reflects addition of features, and accompanies an initial public release. A change in the patchlevel reflects bugfix releases of the stable branch, while on the trunk patchlevels are fairly arbitrary, reflecting regular beta ＠＠ -340,6 +341,8 ＠＠ Individual packages, like the stable branch, may have a listed maintainer. In those cases, the listed maintainer is the gatekeeper. +Please ask before committing to a package with a listed maintainer. +Many, but not all, will be happy to let you do so. ＠heading Guiding Principles ＠＠ -414,7 +417,13 ＠＠ In both cases, an accurate ChangeLog detailing your changes (file and function) should accompany the patch. -You ＠strong{must} reference the GPL correctly in every file. +You ＠strong{must} reference the GPL correctly in every file you change. +That is the law, in the U.S. and in all countries we know about. (If a +file is not under the GPL, please report it as a possible bug. Some +files are not, but it's worth checking. If you wish to contribute a +whole, new file under a non-GPL but GPL-compatible license, that is also +possible. What you may not do is remove or alter others' copyright +attributions, or any license notice that is present.) Manuals must also follow these rules, except that for historical reasons they have various different licenses. ＠emph{Be careful}: it is ＠＠ -431,7 +440,7 ＠＠ Documentation files must be licensed under an approved free license or an OSI-approved open source license. Where possible, GPL-compatible licenses are preferred. If at all possible, avoid the GNU Free -Documentation License, because it ＠emph{is incompatible with the GPL}, +Documentation License, because it is ＠emph{incompatible with the GPL}, implying that text cannot be copied freely between docstrings and the Texinfo manual, except by the copyright holder. ＠＠ -469,7 +478,7 ＠＠ 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. +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 ＠＠ -483,8 +492,8 ＠＠ 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. +reading this ＠emph{Guide}. Well then---presto-chango! you're an +XEmacs developer. That doesn't mean that some developers don't have more privileges than others, that all contributions are accepted, or that some contributions ＠＠ -492,7 +501,7 ＠＠ 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 +contributors never submit code to the project; they simply participate in the newsgroups and mailing lists, giving advice based on their experience to other users. ＠＠ -513,24 +522,24 ＠＠ ＠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. +reinstall XEmacs or its packages regularly, and report any problems. Should participate in ＠value{BETA-LIST}. ＠xref{xemacs-beta}. ＠item Committer -A developer with write access to the XEmacs CVS repository, which may be +A developer with write access to the XEmacs repositories, which may be restricted to specified modules. ＠xref{Committer}. Should participate in ＠value{BETA-LIST} ＠ref{xemacs-beta}, and ＠value{PATCHES-LIST} ＠ref{xemacs-patches}. ＠item Package maintainer A committer with responsibility for integrating a separately maintained -module containing a set of optional libraries with XEmacs. The module +component, containing a set of optional libraries, with XEmacs. The component often constitutes a well-defined application, such as an MUA. ＠xref{XEmacs Package Maintainer}. ＠item Reviewer A developer who may authorize developers, including himself, to write to -the XEmacs CVS repository. ＠xref{XEmacs Reviewer}. Should participate +the XEmacs repositories. ＠xref{XEmacs Reviewer}. Should participate in ＠value{BETA-LIST} ＠ref{xemacs-beta}, ＠value{PATCHES-LIST} ＠ref{xemacs-patches}, and ＠value{REVIEW-LIST} ＠ref{xemacs-review}. ＠＠ -564,7 +573,7 ＠＠ 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 +of a programmer's editor. The ＠dfn{package release engineer} manages the various unbundled applications, the build infrastructure, and the network-based download and install functionality for them. Must participate in ＠value{PATCHES-LIST} ＠＠ -612,9 +621,9 ＠＠ ＠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 +XEmacs repositories are open for anonymous read access, beta testers do not get special access to unpublished code. Rather, beta testers -＠c need ＠xrefs for bug and build reports +＠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 ＠＠ -642,8 +651,8 ＠＠ maintain. Note that, in contrast to the use of this term on many projects, being a committer is simply an administrative convenience; committers must wait for approval to check in changes. -Developers who do not have CVS access contribute by submitting patches -to ＠value{PATCHES-LIST}. +Developers who do not have repository write access contribute by +submitting patches to ＠value{PATCHES-LIST}. Commit access is generally given to those who have submitted several good patches, to ``well-known'' developers on request, and to XEmacs ＠＠ -662,10 +671,12 ＠＠ ＠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 -(a)i{cvs.xemacs.org}}, and the second is to -＠uref{http://www.xemacs.org/Lists/#xemacs-beta, subscribe to +There are a few minor prerequisites to get out of the way. The first is +to get an account on ＠i{alioth.debian.org} so that you can access the +XEmacs 21.5 Mercurial repository, the second is to +＠email{cvs-manager＠(a)xemacs.org,request an account at +(a)i{cvs.xemacs.org}} to access the CVS repository of packages, and the +third is to ＠uref{http://www.xemacs.org/Lists/#xemacs-beta, subscribe to the XEmacs Beta mailing list}. ＠cindex XEmacs User's Guide ＠＠ -675,12 +686,12 ＠＠ ＠c #### fix these urefs!! Developers should be familiar with the -＠uref{http://www.xemacs.org/Documentation/,XEmacs Lisp Manual} +＠uref{http://www.xemacs.org/Documentation/21.5/html/,XEmacs Lisp Manual} ＠ifinfo ＠xref{Top, XEmacs Lisp Reference, , lispref}. ＠end ifinfo as well as the -＠uref{http://www.xemacs.org/Documentation/,XEmacs Manual}. +＠uref{http://www.xemacs.org/Documentation/21.5/html/,XEmacs Manual}. ＠ifinfo ＠xref{Top, XEmacs User's Guide, , xemacs}. ＠end ifinfo ＠＠ -689,9 +700,11 ＠＠ ＠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 +If you think that you may contribute enough to want access to the CVS or +Mercurial +repositories, request access from the ＠email{cvs-manager＠(a)xemacs.org,CVS +Administrator} and get an account on ＠i{alioth.debian.org}. +Generally speaking, if you have contributed to the ＠value{PROJECT} mailing lists and ＠i{comp.emacs.xemacs} newsgroup over the years, you will be given CVS privileges within a few days. If you are new, you may need to find a sponsor on the ＠value{BOARD} to vouch ＠＠ -936,7 +949,7 ＠＠ any part of XEmacs). However, he should feel free to make any changes he thinks useful for his package; he does not need to ask anyone's permission, and may approve or veto submissions by other users, and -incorporate them in -modesthe package as he sees fit. +incorporate them in the package as he sees fit. The responsibility accepted is simply to pay attention to the package. The package maintainer should stay on top of progress in the upstream ＠＠ -1076,8 +1089,8 ＠＠ ＠kbd{make bindist} in your package's top directory. We know this is annoying, but disk space is cheap, and the requirement -for a full build is a one-time thing. After that, you can just do make -bindist in your package's directory. Suggestions for improvement of the +for a full build is a one-time thing. After that, you can just do ＠kbd{make +bindist} in your package's directory. Suggestions for improvement of the process ＠emph{are} welcome, but they must account for the need to provide macro definitions and autoloads. ＠＠ -1200,13 +1213,13 ＠＠ ＠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 +arbitrating conflicts among reviewers, for relations to other projects, +for changes to the development process described in this ＠emph{Guide}, and for giving access to ＠value{PROJECT} resources to developers, including selecting new reviewers. ＠c #### ＠xref{XEmacs Review Board}. -Unlike many projects (in particular, GNU Emacs), the +Unlike many projects, the ＠value{PROJECT} does not have a single authoritative ＠dfn{maintainer}. Policy discussions are conducted on the ＠value{REVIEW-LIST}. Only reviewers are subscribed, but any developer may post. ＠＠ -1228,14 +1241,15 ＠＠ ＠node Appointing New Reviewers, Welcoming New Reviewers, XEmacs Reviewer, XEmacs Reviewer ＠subsection Appointing New Reviewers -＠strong{This node needs improvement!!} +＠c #### This node needs improvement!! ＠cindex ＠value{BOARD} ＠cindex appointing reviewers ＠cindex reviewers, appointing The ＠value{BOARD} is a self-maintaining cabal. New reviewers are -appointed when the Board feels it would improve the project. +appointed when the Board feels having a person as a colleague would +improve the project. ＠＠ -1273,7 +1287,8 ＠＠ 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. +"branch" (actually, the Mercurial branch ＠file{xemacs}). +This includes one's own patches. If you are submitting a patch that you expect to be controversial or that you expect other reviewers to take a strong interest in discussing, you should simply submit it, and note in the abstract that ＠＠ -1395,11 +1410,11 ＠＠ 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 +site), 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. ＠＠ -1439,7 +1454,8 ＠＠ 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 +the repository, tagging the version in the repository, +updating release documentation, creating and uploading tarballs, and making announcements. Release engineers are ＠emph{ex oficio} members of the XEmacs Review Board. That is, if you are willing to accept the responsibility of release engineering, and the Board is ＠＠ -1451,7 +1467,7 ＠＠ 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). +(the Mercurial ＠file{xemacs} branch). ＠＠ -1483,7 +1499,7 ＠＠ ＠table ＠emph ＠item Get the sources. ＠value{PROJECT} tarballs are always distributed as source (except in -the case of the Windows installer), but CVS simplifies management of +the case of the Windows installer), but version control simplifies management of your improvements. (Third-party vendors such as *nix distributions and Cygwin may distribute binary packages, but XEmacs no longer does.) ＠＠ -1493,6 +1509,7 ＠＠ ＠item Test your changes. It's not done until you've proved it works the way you said it would. +As much as possible, tests should be automated, using ＠file{test-harness.el}. ＠item Add a ChangeLog entry. Tell us what you did. ＠＠ -1514,10 +1531,13 ＠＠ maintainability in the implementation. ＠item Assign copyright. -If you like; not required. +If you like you may assign your coppyright, typically to the FSF; but +this is not required. ＠item Commit the patch. -Who commits, how to commit, and when to commit. +Who commits, how to commit, and when to commit are determined by +negotiation between the developer of the patch and the approving +reviewer. ＠item Dispute Resolution Any three developers will give you four ``best ways'' to do it. Now you ＠＠ -1565,7 +1585,8 ＠＠ to be used in GNU Emacs, you will have to resubmit it directly to the GNU Emacs project. (The assignment is acceptable for use in Emacs, but Emacs developers are not allowed to port others' code from XEmacs to GNU -Emacs, even if it's assigned; the original developer must do that.) +Emacs, even if it's assigned; the original developer must participate in +the process.) Get more information about procedures from the ＠email{emacs-devel＠(a)gnu.org,GNU Emacs developers' mailing list} or from ＠＠ -1593,17 +1614,16 ＠＠ ＠section Get the Sources Maybe the developer has never worked on XEmacs before. In that case, -he'll need to -check out the ＠samp{xemacs} module from the CVS repository ＠ref{CVS -Repository}. True, he may already have the whole package because he -built from source after downloading a tarball. However, tarballs often -lag current development by many months, and there's nothing that turns a -maintainer off like a patch that doesn't apply because it was generated -against an old version. Furthermore, the developer needs to keep track -of the original file in order to generate a correct patch, which can be -quite difficult if you go through several iterations working on a complex -issue. It's true that CVS has problems in advanced usage, but for these -simple housekeeping tasks it works very well. Use CVS. +he'll need to check out the ＠samp{xemacs} tree from the Mercurial +repository (＠pxref{Mercurial Repository}), or the package tree from the +CVS repository (＠pxref{CVS Repository}. True, he may already have the +whole package because he built from source after downloading a tarball. +However, tarballs often lag current development by many months, and +there's nothing that turns a maintainer off like a patch that doesn't +apply because it was generated against an old version. Furthermore, the +developer needs to keep track of the original file in order to generate +a correct patch, which can be quite difficult if you go through several +iterations working on a complex issue. ＠＠ -1752,21 +1772,27 ＠＠ Multiple targets with the same text may appear in the same entry. ＠cindex Debian +＠c #### ＠cindex SourceForge +＠cindex XEmacs tracker -For consistency, phrase the issue number as follows (＠pxref{Updating -NEWS}): +If your patch is related to a reported issue, please note the issue in +the ChangeLog. For consistency, phrase the issue number as follows +(＠pxref{Updating NEWS}). For the XEmacs tracker, use ＠example - (closes SF #621632). + (closes issue1234). ＠end example -or +You may also be aware of third party reports, such as in the SourceForge +or Debian trackers. In those cases include the name of the project +maintaining the tracker, and maybe an URL: ＠example + (closes SourceForge #621632). (closes Debian #234234). ＠end example -The Emacs manual has full documentation on the ＠file{ChangeLog} +The XEmacs manual has full documentation on the ＠file{ChangeLog} commands. When you check in the change log, you do not need to supply any log ＠＠ -1782,7 +1808,8 ＠＠ ＠cindex log messages ＠cindex ChangeLog -Log messages should be taken from ＠file{ChangeLog}. Given the +Log messages for Mercurial or CVS checkins +should be taken from ＠file{ChangeLog}. Given the ＠file{ChangeLog} in the previous section, here is what the log for ＠file{fixhtml} might look like: ＠＠ -1797,8 +1824,7 ＠＠ 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?} +present to separate the messages. It is not necessary to add release information since that information will be encoded in the tags. ＠＠ -1845,18 +1871,19 ＠＠ 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 +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 +0, or plain text that can be easily cut and pasted, is the preferred format for the ＠file{ChangeLog} diff. These should be prepended to the changeset. 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. +It is available in the ＠file{xemacs-devel} package. ＠＠ -1997,7 +2024,7 ＠＠ before it will be acceptable. ＠end table -There is currently some controversy on the ＠value{BOARD} about the +There has been controversy on the ＠value{BOARD} about the meaning of a veto. Some reviewers interpret it as unalterable opposition that can only be settled with sabers or pistols, while others see it as a moratorium that might be, or might not be, permanent. ＠＠ -2061,7 +2088,7 ＠＠ is no way to supply a message ID reference; that requirement is nullified. ＠strong{This procedure is not yet in effect, and the commit-trigger has -not yet been implemented at the time of writing. (2005-01-20)} +not yet been implemented at the time of writing. (2009-02-24)} ＠＠ -2169,7 +2196,10 ＠＠ 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). +self-approval). + +(It's arguable that ``full review process'' should mean approval by a +reviewer other than the submitter.) ＠end table ＠＠ -2187,6 +2217,7 ＠＠ ＠menu * Project Website:: +* Mercurial Repository:: * CVS Repository:: * comp.emacs.xemacs:: * xemacs-beta:: ＠＠ -2199,7 +2230,7 ＠＠ -＠node Project Website, CVS Repository, XEmacs Resources on the Internet, XEmacs Resources on the Internet +＠node Project Website, Mercurial Repository, XEmacs Resources on the Internet, XEmacs Resources on the Internet ＠section Project Website ＠strong{Needs review. Adrian?} ＠＠ -2219,8 +2250,38 ＠＠ spaces. +＠node Mercurial Repository, CVS Repository, Project Website, XEmacs Resources on the Internet +＠section Mercurial Repository + +＠cindex Mercurial Repository + +＠c #### update the specific links for convenience!! +The Mercurial Repository contains several branches of the trunk +(currently version 21.5). You can view the repository with an ordinary +browser on the HTTP URL. + +＠table ＠uref +＠item http://hg.debian.org/xemacs/xemacs-beta +The branch from which beta releases are made. Direct commits are not +allowed. Only the gatekeepers (pulling approved patches from the +＠file{xemacs} branch) and the Beta Release Manager may commit +to this branch. The ＠file{xemacs-beta} branch is expected to always be +in a buildable state. It should lag the ＠file{xemacs} branch by less +than a week, unless a patch is found to break the build. + +＠item http://hg.debian.org/xemacs/xemacs +A public-access URL for the bleeding edge. + +＠item hg://hg.debian.org//xemacs/xemacs +The commit access URL for the bleeding edge. Although you cannot easily +push changesets that would create a new head, committers who use named +branches should take care not to push from branches other than +＠file{default}. + +＠end table + -＠node CVS Repository, comp.emacs.xemacs, Project Website, XEmacs Resources on the Internet +＠node CVS Repository, comp.emacs.xemacs, Mercurial Repository, XEmacs Resources on the Internet ＠section CVS Repository ＠cindex CVS Repository ＠＠ -2274,14 +2335,21 ＠＠ ＠node xemacs-winnt, xemacs-review, xemacs-mule, XEmacs Resources on the Internet ＠section The xemacs-winnt Mailing List -＠strong{Write me!} +This list is obsolete, as the NT console is a fully-supported component +of XEmacs since the release of 21.4. Archives are still available at +(a)uref{list-archive.xemacs.org,the XEmacs mailing list archives}. ＠node xemacs-review, , xemacs-winnt, XEmacs Resources on the Internet -＠section The xemacs-winnt Mailing List +＠section The xemacs-review Mailing List -＠strong{Write me!} +The XEmacs Review mailing list is a closed-subscription list where the +XEmacs Reviewers discuss matters requiring privacy, including the most +controversial policies, and personnel matters. If you wish to propose +someone for committer, package maintainer, or reviewer (including +yourself!), post to this list. Be patient; there will be a moderation +delay (to filter spam). _______________________________________________ XEmacs-Patches mailing list XEmacs-Patches(a)xemacs.org http://calypso.tux.org/cgi-bin/mailman/listinfo/xemacs-patches