1. xemacs
  2. general-docs

Commits

stephent  committed 5285ccc

Minor updates, including Mercurial repo information.

  • Participants
  • Parent commits 84469ce
  • Branches default

Comments (0)

Files changed (2)

File ChangeLog

View file
+2009-02-24  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* texi/xemacs/xemacs-devguide.texi:
+	Make various changes to adjust for current reality (especially,
+	describe the Mercurial repository briefly).
+
 2007-05-13  Norbert Koch  <viteno@xemacs.org>
 
 	* Makefile (VERSION): XEmacs package 1.05 released.

File texi/xemacs/xemacs-devguide.texi

View file
 
 @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
 XEmacs Resources on the Internet
 
 * Project Website::             
+* Mercurial Repository::              
 * CVS Repository::              
 * comp.emacs.xemacs::           
 * xemacs-beta::                 
 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.
 
 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
 
 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
 
 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
 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.
 
 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
 
 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
 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.
 
 
 @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}.
 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}
 @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
 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
 @cindex commit access
 @cindex cvs.xemacs.org committer accounts
 
-There are a few minor prerequisites to get out of the way. The first is
-to @email{cvs-manager@@xemacs.org,request an account at
-@i{cvs.xemacs.org}}, and the second is to
-@uref{http://www.xemacs.org/Lists/#xemacs-beta, subscribe to
+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@@xemacs.org,request an account at
+@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
 
 @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
 @cindex mailing lists, xemacs-design
 @cindex committer
 
-If you think that you may contribute enough to want access to the CVS
-repository, request access from the @email{cvs-manager@@xemacs.org,CVS
-Administrator}.  Generally speaking, if you have contributed to the
+If you think that you may contribute enough to want access to the CVS or
+Mercurial
+repositories, request access from the @email{cvs-manager@@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
 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
 @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.
 
 @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.
 @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.
 
 
 
 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
 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.
 
 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
 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).
 
 
 
 @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.)
 
 
 @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.
 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
 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@@gnu.org,GNU Emacs developers' mailing list} or from
 @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.
 
 
 
 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}):
+@c #### @cindex SourceForge
+@cindex XEmacs tracker
+
+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
 @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:
 
 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.
 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.
 
 
 
 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.
 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)}
 
 
 
 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
 
 
 
 @menu
 * Project Website::             
+* Mercurial Repository::              
 * CVS Repository::              
 * comp.emacs.xemacs::           
 * xemacs-beta::                 
 
 
 
-@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?}
 spaces.
 
 
-
-@node CVS Repository, comp.emacs.xemacs, Project Website, XEmacs Resources on the Internet
+@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, Mercurial Repository, XEmacs Resources on the Internet
 @section CVS Repository
 
 @cindex CVS Repository
 @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
+@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
-
-@strong{Write me!}
+@section The xemacs-review Mailing List
+
+The XEmacs Review mailing list is a closed-subscription list where the
+XEmacs Reviewers discuss matters requiring privacy, including the most
+controversial policies, and personnel matters.  If you wish to propose
+someone for committer, package maintainer, or reviewer (including
+yourself!), post to this list.  Be patient; there will be a moderation
+delay (to filter spam).