[PATCH general-docs] update DevGuide for Mercurial
Mike Kupfer <[email protected]> Fri, 10 Jul 2015 18:12:16 -0700
| Newsgroups | gmane.emacs.xemacs.patches |
|---|---|
| Message-ID | <[email protected]> |
--=-=-= Content-Type: text/plain Attached is a patch to reflect the move from CVS to Mercurial, as well as to provide some additional guidance to package maintainers. It's pretty large, so I'll wait at least until 1 August before pushing. And if anyone wants more time than that to review it, let me know; I don't want anyone to feel rushed. A few notes and open questions on the changes: - I left in some references to CVS, especially in text that talks about email addresses and the release process, since I wasn't sure about the current process. - I left in the @cindex tags that refer to CVS. Should those just be changed from "CVS" to "Mercurial"? - There was some email back in May about CNAMEs and Bitbucket--are any changes needed to the DevGuide to deal with that? - I didn't change the process rule in Section 5.10 that says "(t)he log message should refer unambiguously to the 'COMMIT' message, preferably via the RFC 2822 message ID". This is something we don't seem to be doing, so should that text remain? cheers, mike 2015-07-10 Mike Kupfer <[email protected]> * texi/xemacs/xemacs-devguide.texi: Update to better reflect the current Mercurial-based workflow. Remove most references to CVS. Add information for package maintainers, some of which is independent of Mercurial. (Updating and Merging with Mercurial): New. (Committing and Pushing a Package Change): New. (Updating a Package to a New Upstream Version): New. --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=devguide-hg-patch.diffs Content-Description: patch diff --git a/texi/xemacs/xemacs-devguide.texi b/texi/xemacs/xemacs-devguide.texi --- a/texi/xemacs/xemacs-devguide.texi +++ b/texi/xemacs/xemacs-devguide.texi @@ -10,9 +10,9 @@ @c Developer's Guide variables. @set DEVGUIDE @cite{XEmacs Developer's Guide} -@set EDITION 0.7 -@set UPDATED 2009-02-24 -@set UPDATE-MONTH February, 2009 +@set EDITION 0.8 +@set UPDATED 2015-07-10 +@set UPDATE-MONTH July, 2015 @c Other variables. @set XEMACSORG XEmacs.ORG @@ -26,7 +26,6 @@ @set DESIGN-LIST the @email{xemacs-design@@xemacs.org,XEmacs Design} mailing list @set REVIEW-LIST the @email{xemacs-review@@xemacs.org,XEmacs Review} mailing list @set PATCHES-LIST the @email{xemacs-patches@@xemacs.org,XEmacs Patches} mailing list -@set CVS-LIST the @email{xemacs-cvs@@xemacs.org,XEmacs CVS Notices} mailing list @set BUILDREPORTS-LIST the @email{xemacs-buildreports@@xemacs.org,XEmacs Build Reports} mailing list @copying @@ -166,7 +165,6 @@ * Project Website:: * Mercurial Repository:: -* CVS Repository:: * comp.emacs.xemacs:: * xemacs-beta:: * xemacs-design:: @@ -582,7 +580,7 @@ @item Postmaster @itemx Webmaster -@itemx CVS Manager +@itemx Repository Manager Administrators of the various Internet-based services important to XEmacs users and developers. @c #### Write nodes for these posts! @@ -647,7 +645,7 @@ @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 +into the source repository, including changes to private branches they may maintain. Note that, in contrast to the use of this term on many projects, being a committer is simply an administrative convenience; committers must wait for approval to check in changes. @@ -669,14 +667,13 @@ @subsection Commit Access @cindex commit access -@cindex cvs.xemacs.org committer accounts +@cindex bitbucket.org committer accounts 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 +to get an account on @i{bitbucket.org} so that you can access the +Mercurial repositories for XEmacs core code and packages. +The second is to +@uref{http://www.xemacs.org/Lists/#xemacs-beta, subscribe to the XEmacs Beta mailing list}. @cindex XEmacs User's Guide @@ -700,13 +697,12 @@ @cindex mailing lists, xemacs-design @cindex committer -If you think that you may contribute enough to want access to the CVS or -Mercurial +If you think that you may contribute enough to want write access to the source repositories, request access from the @email{cvs-manager@@xemacs.org,CVS -Administrator} and get an account on @i{alioth.debian.org}. +Administrator} and get an account on @i{bitbucket.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 +the years, you will be given write privileges within a few days. If you are new, you may need to find a sponsor on the @value{BOARD} to vouch for you. @@ -772,36 +768,14 @@ 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 (120+ MB -as of 2007/02). - -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. +for all those involved. See the section ``XEmacs Package Maintainer'' +in the XEmacs Developer Guide for additional information and tips. Building ======== For a quick start to building packages, see INSTALL under the packages/ -dir you've checked out from CVS. +dir where you set up a local source tree. Patches ======= @@ -841,14 +815,14 @@ 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 + 1) The packages repository is a "stable" branch, please do all that you can to keep it that way. 2) In the Makefile you'll see "VERSION=" and "AUTHOR_VERSION=", please don't ever alter the former. We do that as part of the package release process. - 3) When you update redtape in CVS it'd be great if you could + 3) When you update redtape on Bitbucket it'd be great if you could either drop me a quick email or post to xemacs-beta saying that redtape is ready for release. @@ -856,13 +830,13 @@ ----------------------------------------------------- You - hack hack hack - - cvs diff -u > cool-new-patch.diff + - hg diff > cool-new-patch.diff - submit to xemacs-patches - unless there are objections, or if it's "obviously correct", - commit to CVS + commit and push to Bitbucket Us - - cvs update + - hg pull -u - build new version of redtape - upload to the "Pre-Release" directory of ftp.xemacs.org - announce release on xemacs-beta @@ -930,6 +904,9 @@ @menu * The Package Maintainer Role:: * Getting Started as a Package Maintainer:: +* Updating and Merging with Mercurial:: +* Committing and Pushing a Package Change:: +* Updating a Package to a New Upstream Version:: * Advice to Package Maintainers:: @end menu @@ -970,28 +947,39 @@ -@node Getting Started as a Package Maintainer, Advice to Package Maintainers, The Package Maintainer Role, XEmacs Package Maintainer +@node Getting Started as a Package Maintainer, Updating and Merging with Mercurial, The Package Maintainer Role, XEmacs Package Maintainer @subsection Getting Started as a Package Maintainer -The first step is to check out the package from CVS in -read-write mode. This is done as follows: +The first step is to clone the package from the source repository. + +The XEmacs packages are organized using Mercurial subrepositories (aka +subrepos). This means that each package lives in its own Mercurial +repo, plus there's one more repo at the top level. Although it's +possible to clone a single package repo, it's better to clone the +entire tree, so that you get the build infrastructure that the top +level provides. The simplest way to do this is as follows: @example -export CVSROOT=:ext:xemacs@@cvs.xemacs.org:/pack/xemacscvs -export CVS_RSH=/usr/bin/ssh -cvs checkout packages +hg clone https://bitbucket.org/xemacs/xemacs-packages mypackages @end example -This will take a while, and about 120MB of space. It's possible to do +This will take a while, and about 210MB of space. It's possible to do without most of the packages (for example, most modes can delete all of the mule-packages subtree), but the Lisp programming language makes it very easy to call functions in one package from another, and -interdependencies are frequent. Unless one is really really tight for -space, it's best to start by just checking out the whole thing, and -prune it back later. - -The package developer is welcome to change anything in the subtree that -contains the package. However, there are a couple of administrative +interdependencies are frequent. + +The next step is to configure any packages that you want to change so +that they can be pushed back to Bitbucket. In the @file{.hg/hgrc} for +each such package, change the https URL to an ssh URL, i.e., + +@example +default=ssh://hg@@bitbucket.org/xemacs/@var{package_name} +@end example + +The package developer is welcome to change anything in the repo for +his or her +package. However, there are a couple of administrative files that are conceptually the "property" of the package system. These are @file{package-info.in} and the @file{Makefile}. There is almost surely no need to change either at this time, except to change the @@ -1005,18 +993,22 @@ == VERSION}; ask the package release engineer about it if that seems attractive. -So now you can (with the above environment settings) +So now you can @example -cd packages/xemacs-packages/@var{package_name} +cd mypackages/xemacs-packages/@var{package_name} xemacs Makefile # change MAINTAINER to your name and address -# make a patch with cvs diff > my.patch and send it to XEmacs Patches -cvs commit -m "Update MAINTAINER name and address." Makefile +# make a patch with hg diff > my.patch and send it to XEmacs Patches +hg commit -m "Update MAINTAINER name and address." Makefile +hg push @end example which is a good test that everything is working. You can find out -more about CVS and the XEmacs repository at @url{http://cvs.xemacs.org}. +more about Mercurial and the XEmacs repository at +@url{http://www.xemacs.org/Develop/hgaccess.html}. Additional +documentation on Mercurial Subrepositories is at +@url{http://mercurial.selenic.com/wiki/Subrepository}. Many maintainers who have a separate repository for the upstream project do not send patches, but simply announce a synch to upstream. However, @@ -1030,11 +1022,8 @@ is set to something useful. Now you can build a test package by simply typing @kbd{make bindist}. -Then copy the updated upstream files over the existing ones. Try -making a package with make bindist. Use the new code, too, to see if -you find any bugs. If not, you can commit the new files to CVS. - -When you make a commit, you should notify the package release engineer, +When you push a change to the master packages repository, you should +notify the package release engineer, currently @email{viteno@@xemacs.org,Norbert Koch}, about your intentions. Norbert is pretty aggressive about making new packages and putting them up for download. If you don't want that after a given @@ -1046,7 +1035,6 @@ @example @var{firstname.lastname}@@xemacs.org -@var{cvsuser}@@xemacs.org @end example You can use these publically as you see fit, or not. The package @@ -1066,9 +1054,118 @@ about the XEmacs package in upstream project channels rather than XEmacs channels. - - -@node Advice to Package Maintainers, , Getting Started as a Package Maintainer, XEmacs Package Maintainer +@node Updating and Merging with Mercurial, Committing and Pushing a Package Change, Getting Started as a Package Maintainer, XEmacs Package Maintainer +@subsection Updating and Merging with Mercurial + +Although the package maintainer is normally the only person to update +a package, it's possible that the repo on Bitbucket will contain +changes that aren't in your local repo. If this happens, you will +need to merge in those changes before pushing your changes. + +As a general recommendation, you should commit your local changes +before pulling from the parent repository. Having your changes +committed means they will not be lost in case something goes awry +during the merge process. + +If you need to run @samp{hg merge}, you should do an @samp{hg commit} +after you have finished merging the changes. This will make it easier +to distinguish additional work from changes that resulted from the +merge. + +Assuming you have the entire package tree, the most reliable way to get an +update is to do @samp{hg pull -u} in the top-level repository. The +@samp{-u} (or +a separate @samp{hg update}) is necessary to pull the subrepo updates from +the parent repository. + +If a merge is needed in your package subrepo, Mercurial will indicate it +when processing your subrepo +with the string @samp{+1 heads}. You can then use +the normal @samp{hg merge} and @samp{hg commit} commands within the subrepo. + + +@node Committing and Pushing a Package Change, Updating a Package to a New Upstream Version, Updating and Merging with Mercurial, XEmacs Package Maintainer +@subsection Committing and Pushing a Package Change + +Normally you will just push changes from your package (sub)repo, not +the top-level packages repo. You can use @samp{hg stat} to check for +uncommitted changes. After your final commit, you can use +@samp{hg outgoing} to list the changeset(s) that you will be pushing. + +If your push fails with an error message about creating multiple +heads, that usually means that changes have been made in the parent +repo since the last time you pulled from it. It's usually best to +pull down those changes and (re)run @samp{hg merge}. Retest as needed, +review your changes, commit, and try again to push. + + +@node Updating a Package to a New Upstream Version, Advice to Package Maintainers, Committing and Pushing a Package Change, XEmacs Package Maintainer +@subsection Updating a Package to a New Upstream Version + +If the XEmacs package sources are exactly the same as the upstream +sources, updating to a new upstream version is easy: just copy in the +new sources and update @samp{AUTHOR_VERSION} in the @file{Makefile}. +Build, test, commit, and push. + +Often, though, the XEmacs package has diverged from upstream. In this +situation, the package maintainer can keep a pristine copy of the +most recent upstream version (i.e., the version that the XEmacs +package is based on). Updating to a new upstream version then +involves the following steps: + +@enumerate +@item +Diff the new upstream version against the previous upstream version to +generate a patch file. + +@item +If necessary, massage the patch file to reflect the XEmacs file +layout, or to remove diffs for files that are not in the XEmacs +package. + +@item +Make sure that your repository has the latest changesets from +Bitbucket. + +@item +Apply the patch and resolve any conflicts by hand. + +@item +Manually register any new files with Mercurial (@samp{hg add}) and remove +any files that have been deleted (@samp{hg rm --after}). + +@item +Build your package (and optionally build the entire package tree). +Test as seems appropriate. + +@item +When you are ready (e.g., after testing), commit and push the new +version as described in the previous section. + +@end enumerate + +After pushing, monitor @uref{http://www.contactor.se/~matsl/smoketest/, +the package smoketest} in case your changes break the build of other +packages. + +@heading ChangeLog files + +Many upstream packages provide their own @file{ChangeLog} files. You +may wish to rename those to @file{ChangeLog.upstream} (or some +variation), so that they are separate from the XEmacs @file{ChangeLog} +files. You can refer to the upstream @file{ChangeLog} file in the +@file{ChangeLog} entry that you create when updating to a new upstream +release. For example: + +@example + YYYY-MM-DD J. Random Hacker <jrh@@xemacs.org> + + * Sync with foobar 2.7. + Please see the ChangeLog.upstream files for details. +@end example + + +@node Advice to Package Maintainers, , Updating a Package to a New Upstream Version, XEmacs Package Maintainer @subsection Advice to Package Maintainers This section contains some as yet unorganized advice to package @@ -1083,8 +1180,9 @@ the @file{xemacs-base} package, for example. Therefore the recommended procedure is to check out the whole package tree, configure @file{Local.rules}, and do a full build with @kbd{make} from the top. -(After that you should keep the tree up-to-date with @kbd{cvs update --dP} and occasionally do a @kbd{make} to keep things in order.) Having +(After that you should keep the tree up-to-date, +@xref{Updating and Merging with Mercurial}, and +occasionally do a @kbd{make} to keep things in order.) Having done this once, you can thereafter normally simply do @kbd{make} and @kbd{make bindist} in your package's top directory. @@ -1094,6 +1192,36 @@ process @emph{are} welcome, but they must account for the need to provide macro definitions and autoloads. +@heading Cloning from your local copy + +The clone command in @ref{Getting Started as a Package Maintainer} +produces a packages tree that can be +built, but because of the way the subrepositories are laid out, you +cannot clone it further. If you wish to create further clones, you +should create one more directory layer, e.g., + +@example +mkdir mypackages +cd mypackages +hg clone https://bitbucket.org/xemacs/xemacs-packages +@end example + +and then run the following script. In the example above, you would +run it from the @file{mypackages/xemacs-packages} directory. + +@example +#! /bin/sh +top=$(basename $(pwd)) +for d in mule-packages xemacs-packages; do + for f in $d/*; do + [ -d $f ] && ln -s $top/$f .. + done +done +mv ../Sun ../sun +mv ../hm--html-menus ../hm-html-menus +@end example + + @heading Lisp macros and autoloads Lisp provides @dfn{macros}, which involve @dfn{expansion}, which means @@ -1135,6 +1263,19 @@ since make itself and simply starting XEmacs to do the compilation are pretty time-consuming. +@heading Maintaining Package Metadata + +If you change the packages that your package depends on, or if you +change the libraries that your package provides, you will need to edit +one or more files to reflect those changes. + +To update the packages that your package depends on, edit the +@samp{REQUIRES} list in the package's +@file{Makefile}. + +To update the list of libraries that your package provides, edit the +@samp{provides} clause in the package's @file{package-info.in}. + @heading For the future Some attempts have been made to track the dependencies on macros and @@ -1145,6 +1286,37 @@ just build the packages, and set up dependencies when errors occur. +@heading XEmacs-Specific Changes + +You can make XEmacs-specific changes easier to find by tagging them +with this comment: + +@example +;; XEmacs change +@end example + +Of course, the more variances there are between the upstream code and +the XEmacs package, the harder it will be to update to new upstream +versions. So the general recommendation is to work with the upstream +developers to get any such changes incorporated into the upstream code +base. + +@heading Changes to Other Packages or Top-Level + +Sometimes your changes may require changes to code that you don't own. +For example, API changes in a new release of your package may break +other packages. Also, the top-level repo has some package-specific +data, like whether the sources are in the package's top-level +directory or in a @file{lisp} subdirectory@footnote{See +@samp{package-directory-map} in @file{package-compile.el}.}. +So it's possible you will need +to make changes in the top-level repo as well. + +If you need to make changes in code that you don't own, send mail to +XEmacs Beta to ask for assistance. Describe the changes that you want +to make (and why) and ask for instructions on how to proceed. + + @heading Getting Help with Your Package If you want advice on the code itself, just post it to XEmacs Patches, @@ -1209,7 +1381,7 @@ @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 +for application to the XEmacs core code. 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 @@ -1401,22 +1573,22 @@ mailing list administrator at xemacs-mailmaint@@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 +bitbucket.org. If you have any trouble due to extensions of your permissions, let the CVS Managers know at cvs-manager@@xemacs.org. The directions at - http://www.xemacs.org/Develop/cvsaccess.html + http://www.xemacs.org/Develop/hgaccess.html seem to be pretty clear. XEmacs uses facilities at Tux.org (mailing lists, FTP archive, and web -site), 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. +site), in addition to the source code management provided by +Bitbucket. There is also a web site mirror at SourceForge, but this +is rarely of interest to anyone except the webmaster. If you need +access to Tux.org, let me know. The administrators are +very helpful within the constraints of their security policies, and if +there is a reasonable need, they generally respond by providing +access. If you have any questions, feel free to ask any of the reviewers directly (see http://www.xemacs.org/Develop/jobs.html) or post to @@ -1516,10 +1688,10 @@ @item Create the patch. Dot the i's, cross the t's. Make sure that it's easy to add to the code -base. The best way is by using @code{cvs diff -uN} against the tip of +base. The best way is by using @code{hg diff} against the tip of the branch or trunk you intend to have the patch applied to. The -exception is ChangeLog patches, which may be generated using @code{cvs -diff -U 0 ChangeLog}, or submitted as plain test. +exception is ChangeLog patches, which may be generated using @code{hg +diff -U 0 ChangeLog}, or submitted as plain text. @item Submit the patch. Compose the message, especially the Subject: header, so it's easy to @@ -1614,9 +1786,8 @@ @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} 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 +he'll need to check out the source tree from the Mercurial +repository (@pxref{Mercurial Repository}). True, he may already have the whole package because he built from source after downloading a tarball. However, tarballs often lag current development by many months, and there's nothing that turns a maintainer off like a patch that doesn't @@ -1720,7 +1891,7 @@ 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 +visibility to the changes to those who do not have access to the source repository. Here is an example @file{ChangeLog} entry: @@ -1808,7 +1979,7 @@ @cindex log messages @cindex ChangeLog -Log messages for Mercurial or CVS checkins +Log messages for Mercurial 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: @@ -1830,12 +2001,9 @@ 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. +operation. At best, it will be a keystroke or two. Currently cut and +paste is required because the XEmacs version of VC does not support +Mercurial. I specify the following for @code{log-edit-hook} to make life easier: @@ -1859,13 +2027,13 @@ 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 +GNU diffutils, or implemented by Mercurial. 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 +-urN} format produced by GNU diff 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 +you use older diffs, 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 @@ -1880,12 +2048,6 @@ 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. - - @node Submit the Patch, Patch Review, Create the Patch, The Work Flow @section Submit the Patch @@ -1899,7 +2061,7 @@ 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 +should indicate the branch or package 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 @@ -1951,10 +2113,6 @@ [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 * Optional Alternate Procedure for Reviewers:: @end menu @@ -1967,7 +2125,8 @@ 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 +Instead, the responsible reviewer simply commits the patch, and the +repository commit-trigger will automatically generate and post the patch to @value{PATCHES-LIST}. This may be referred to as @dfn{implicit self-approval}. @@ -2062,11 +2221,12 @@ @cindex patch, committing a @cindex committing a patch -Once the patch has been approved, it should be checked in to CVS as soon +Once the patch has been approved, it should be pushed to the source +repository 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 +requirement is meaningless.) The changeset 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.) @@ -2080,7 +2240,7 @@ @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 +In the case of implicit self-approval, the changeset log message should describe the rationale for the patch, and list the affected modules and subdirectories in the tree. This should be enough to point reviewers to the relevant ChangeLog diffs, which will automatically be included. @@ -2209,7 +2369,7 @@ @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}. +available as the module @emph{xemacsweb}. There should also be a node for the Emacs Wiki. @@ -2218,7 +2378,6 @@ @menu * Project Website:: * Mercurial Repository:: -* CVS Repository:: * comp.emacs.xemacs:: * xemacs-beta:: * xemacs-design:: @@ -2244,13 +2403,13 @@ @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 +simply check out the @file{xemacsweb} module, make your changes, and check it in. The commit script takes care of generating the HTML and pushing the changes to the web servers' document spaces. -@node Mercurial Repository, CVS Repository, Project Website, XEmacs Resources on the Internet +@node Mercurial Repository, comp.emacs.xemacs, Project Website, XEmacs Resources on the Internet @section Mercurial Repository @cindex Mercurial Repository @@ -2261,7 +2420,7 @@ browser on the HTTP URL. @table @uref -@item http://hg.debian.org/xemacs/xemacs-beta +@item https://bitbucket.org/xemacs/xemacs-beta The branch from which beta releases are made. Direct commits are not allowed. Only the gatekeepers (pulling approved patches from the @file{xemacs} branch) and the Beta Release Manager may commit @@ -2269,10 +2428,10 @@ 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 +@item https://bitbucket.org/xemacs/xemacs A public-access URL for the bleeding edge. -@item hg://hg.debian.org//xemacs/xemacs +@item ssh://hg@@bitbucket.org/xemacs/xemacs The commit access URL for the bleeding edge. Although you cannot easily push changesets that would create a new head, committers who use named branches should take care not to push from branches other than @@ -2281,20 +2440,7 @@ @end table -@node CVS Repository, comp.emacs.xemacs, Mercurial Repository, XEmacs Resources on the Internet -@section CVS Repository - -@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 +@node comp.emacs.xemacs, xemacs-beta, Mercurial Repository, XEmacs Resources on the Internet @section The Usenet Newsgroup comp.emacs.xemacs @strong{Write me!} @@ -3281,7 +3427,7 @@ @cindex src @cindex Debian -When the @code{src} module is released (@pxref{CVS Repository}), the +When the @code{src} module is released, 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 @@ -3392,7 +3538,7 @@ 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. +automatically updated, and used to identify the Mercurial changeset. Except in cases involving creation of a new stable branch, update of the version information simply requires bumping @samp{emacs_beta_version} @@ -3419,14 +3565,13 @@ @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. +the software is released. With Mercurial, 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. +patch number. A hyphen is used for historical reasons. The stable release branch tag doubles as a tag of the most recent release. While this is not quite true during the process of @@ -3446,37 +3591,10 @@ @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 Full distro -@tab xemacs-X.Y.Z.tar.gz - -@item Patch -@tab xemacs-X.Y.Z-X.Y.(++Z).patch.gz - -@item Sources only -@tab xemacs-X.Y.Z-src.tar.gz - -@item Compiled Lisp -@tab xemacs-X.Y.Z-elc.tar.gz - -@item Formatted Info -@tab xemacs-X.Y.Z-info.tar.gz - -@end multitable -@end quotation @cindex tarballs, making @cindex tarballs, naming @@ -3485,8 +3603,6 @@ @cindex Makefile targets, dist @cindex version numbers -The tarballs listed in the table above are built as follows: - @strong{Write me!} @node Creating @value{XEMACSORG} Releases, Updating the Tracker, Creating Tarballs, File Releases @@ -3799,7 +3915,7 @@ 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 +Guide} is generated directly from Texinfo, and checked in as HTML rather than @file{genpage} source. The validator used by @code{make validate} is based on the PSGML --=-=-= Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ XEmacs-Patches mailing list [email protected] http://lists.xemacs.org/mailman/listinfo/xemacs-patches --=-=-=--