changeset: 5546:d54278e74d71
tag: tip
user: Stephen J. Turnbull <stephen(a)xemacs.org>
date: Mon Aug 08 23:10:47 2011 +0900
files: man/ChangeLog man/internals/internals.texi
description:
Add some working with Mercurial stuff.
diff -r 69de75c48efa -r d54278e74d71 man/ChangeLog
--- a/man/ChangeLog Mon Aug 08 13:57:20 2011 +0900
+++ b/man/ChangeLog Mon Aug 08 23:10:47 2011 +0900
@@ -1,3 +1,13 @@
+2011-08-08 Stephen J. Turnbull <stephen(a)xemacs.org>
+
+ * internals/internals.texi (Mercurial Techniques): New.
+ (Mercurial Basics): New.
+ (Preserving Existing Changes with Mercurial Queues): New.
+ (Top): Update menus.
+ (Regression Testing XEmacs): Update node pointers.
+ (CVS Techniques): Update node pointers. Note obsolescence of CVS.
+ Add @ref to Mercurial Techniques.
+
2011-06-25 Aidan Kehoe <kehoea(a)parhasard.net>
* lispref/os.texi (Translating Input):
diff -r 69de75c48efa -r d54278e74d71 man/internals/internals.texi
--- a/man/internals/internals.texi Mon Aug 08 13:57:20 2011 +0900
+++ b/man/internals/internals.texi Mon Aug 08 23:10:47 2011 +0900
@@ -349,6 +349,7 @@
* The Build Configuration System::
* Rules When Writing New C Code::
* Regression Testing XEmacs::
+* Mercurial Techniques::
* CVS Techniques::
* XEmacs from the Inside::
* Basic Types::
@@ -442,6 +443,11 @@
* How to Regression-Test::
* Modules for Regression Testing::
+Mercurial Techniques
+
+* Mercurial Basics::
+* Preserving Existing Changes with Mercurial Queues::
+
CVS Techniques
* Creating a Branch::
@@ -6356,7 +6362,7 @@
configure --with-mule --use-union-type --error-checking=all
@end example
-@node Regression Testing XEmacs, CVS Techniques, Rules When Writing New C Code, Top
+@node Regression Testing XEmacs, Mercurial Techniques, Rules When Writing New C Code,
Top
@chapter Regression Testing XEmacs
@cindex testing, regression
@@ -6621,10 +6627,246 @@
@code{Check-Message}. The other files are test files, testing various
XEmacs facilities. @xref{Regression Testing XEmacs}.
-@node CVS Techniques, XEmacs from the Inside, Regression Testing XEmacs, Top
+@node Mercurial Techniques, CVS Techniques, Regression Testing XEmacs, Top
+@chapter Mercurial Techniques
+@cindex Mercurial techniques
+
+@dfn{Mercurial} is the @emph{distributed version control system} used to
+manage the XEmacs core code. We plan to migrate the packages as well in
+the near future. The command used is @code{hg}; the entire system is
+implemented as subcommands of the @code{hg} command.
+
+@menu
+* Mercurial Basics::
+* Preserving Existing Changes with Mercurial Queues::
+@end menu
+
+@node Mercurial Basics, Preserving Existing Changes with Mercurial Queues, Mercurial
Techniques, Mercurial Techniques
+
+@subheading Installing Mercurial
+
+Most people have some kind of package manager to help install free
+software. Invariably a reasonably fresh version of Mercurial is
+available. XEmacs doesn't do anything particularly tricky in its
+repositories, so unless you're one of those folks who likes to spend
+more time fiddling with your infrastructure than developing, the
+packaged Mercurial should be more than sufficient. Somewhat fresher
+versions may be available in prepackaged form from
+@uref{http://mercurial.selenic.com, the Mercurial Project}, if you like
+to stay on the leading edge.
+
+@subheading Documentation
+
+The primary online command for getting help on Mercurial is @code{hg
+help}.
+
+@subheading What is the XEmacs repository URL?
+
+For up-to-date information about this, other information about accessing
+the repository @strong{including making your first clone of the
+repository}, and availability of branches, please refer to our website,
+@uref{http://www.xemacs.org/Develop/hgaccess.html}.
+
+@subheading What's so special about ``distributed'' version control systems?
+
+Very little, for occasional contributors. So don't worry about it; the
+commands are you used to with CVS or Subversion will work pretty much as
+is. There are two important differences:
+
+@table @strong
+@item update
+In version control, @dfn{update} means to refresh the versions of files
+in your workspace. In a distributed system, however, there are two
+possible sources: the @dfn{project repository}, and your own @dfn{clone}
+(local repository) which is a more or less up-to-date copy of the
+project repository, including all the history information and historical
+revisions.
+
+@dfn{update} is taken to mean @emph{refresh from the clone}, and a new
+command @dfn{pull} is defined to mean @emph{copy history from the
+project repository to the clone}. Thus, to get new work from other
+contributors applied to your repository, you need to pull, then update.
+Normally the source for pull defaults to the project repository you
+cloned from, and the version to update to defaults to the @dfn{tip}
+(latest version in the clone), so in principle you can abbreviate to
+
+@example
+hg pull
+hg update
+@end example
+
+@noindent
+In fact, Mercurial allows a further abbreviation, to @code{hg pull -u}.
+
+@item commit
+The other direction is similar. The @dfn{commit} command refers to the
+@emph{clone}. A new command, @dfn{push} is used to copy local history
+to the project repository. Unlike the @code{pull} command, however,
+there is no very short way to say ``command @emph{and} push.''
+@end table
+
+@subheading Mercurial Extensions and .hgrc
+
+Third parties provide many extensions to Mercurial. (In fact, the
+Mercurial Project often distributes new functionality as extensions,
+until the UI has stabilized.) Extensions are just as easy to use as
+core commands, and well-written extensions provide their documentation
+via @code{hg help} just like the core. The main difference is that core
+commands are always available, but extensions must be enabled. This is
+done in the extensions section of @file{~/.hgrc}. Here's one of mine:
+
+@example
+[ui]
+username = Stephen J. Turnbull <stephen@(a)xemacs.org>
+ignore = ~/.hgglobalignore
+
+[extensions]
+hgext.hgk =
+hgext.mq =
+hgext.rebase =
+@end example
+
+All of the extensions mentioned above are distributed with Mercurial
+itself, so enabing them is particularly simple. A locally written or
+third-party extension would have a path-to-module after the equal sign.
+The first two extensions above are recommended for all contributors.
+Some contributors may like to use the rebase extension as well, and
+sometimes it's a good way to dig yourself out of a hole. Others hate
+it; if you are thinking about using it, you should be careful, and you
+should never @code{push} a rebased branch without coordinating with the
+project.
+
+@table @code
+@item hgk
+A browser for the history graph, showing relationships among versions.
+Provides the @code{view} command.
+
+@item mq
+@emph{Mercurial queues} are a way of managing sequences of patches,
+similar to the ``quilt'' program made famous by some Linux maintainers.
+It allows you to distinguish between your local changes and ``official''
+ones. Provides many commands beginning with the letter ``q''.
+
+@item rebase
+Rebasing is an alternative technique for managing sequences of patches.
+However, it uses branches rather than patches, and can produce a very
+confusing public history if used indiscriminately. Provides the
+@code{rebase} command.
+@end table
+
+
+@node Preserving Existing Changes with Mercurial Queues, , Mercurial Basics, Mercurial
Techniques
+@section Preserving Existing Changes with Mercurial Queues
+@cindex preserving existing changes with mercurial queues
+@cindex mercurial queues, preserving existing changes with
+
+When first working with a distributed VCS, you may find yourself
+creating a series of unrelated changes in the workspace. Now you feel
+stuck: you worry that you if you commit now, you'll pull in unrelated
+changes. But Mercurial won't let you merge until you have committed?
+Here's how to use Mercurial queues to push ``just this fix'' without
+also pushing unrelated, uncommited changes also present in the
+workspace. This will also set you up for more effective workflow in the
+future.
+
+First, @emph{mq} is an extension, which must be enabled before use. Edit
+(a)file{$HOME/.hgrc} and add these two lines:
+
+@example
+[extensions]
+ hgext.mq =
+@end example
+
+@noindent
+If you already have an [extensions] section, omit the first line.
+
+Suppose the change that you are ready to push is a check for a valid
+drive letter on the Windows platform. It affects @file{src/nt.c}, and
+of course @file{src/ChangeLog}. Assume you have no other changes to these
+files. It is important to do this step now, before handling other
+changes! (In general, it's a good idea to create your @i{mq} patches in
+approximately the order you will submit them. There are ways to
+override that order, using ``guards,'' but that's a little tedious.
+Recent versions of Mercurial queues have an option to reorder patches
+when applying them: @samp{hg qpush --move @var{patch-name}}.)
+
+Initialize an @emph{mq} patch for this change:
+
+@example
+hg qnew -f -m "Check first whether drive is valid." valid-drive \
+ src/ChangeLog src/nt.c
+@end example
+
+@noindent
+View @file{.hg/patches/valid-drive} and make sure it is the patch you
+want to push.
+
+Now make patches for other changes. For a change to @file{foo.el},
+(a)file{foo-msw.el}, and @file{lisp/ChangeLog} it would look like
+
+@example
+hg qnew -f -m "Frob foo." frob-foo lisp/foo.el lisp/foo-msw.el \
+ lisp/ChangeLog
+@end example
+
+@noindent
+Do this until there are @emph{no} changes left (@kbd{hg status} reports
+no modified files).
+
+I strongly recommend that you do this @emph{now}. This is probably the
+best way to organize your work when you make many small changes.
+However, if you have overlapping changes that you can't easily sort out,
+or just don't feel like doing that, you can just
+
+@example
+hg qnew -f -m "DON'T COMMIT ME!" big-ball-of-mud
+@end example
+
+@noindent
+instead.
+
+Now let's commit the patch you want to push. If you feel paranoid, you
+can view all the patches in @file{.hg/patches} to make sure they look
+OK.
+
+@example
+hg qpop --all # unapply --all patches
+hg status # should report no modified files
+hg qpush # note, no argument needed
+hg qapplied # will report "valid-drive" because that was
+ # the first patch you created (it's a queue!!)
+hg qfinish --applied # convert valid-drive from a patch to a commit
+# Make sure it's OK.
+hg log -r tip # message you gave in 'qnew -m' is the
+ # log message
+@end example
+
+@noindent
+Update and push.
+
+@example
+hg pull -u # should work without complaint since you
+ # don't say you have any commits
+hg push # Yay!
+@end example
+
+That looks like a lot of work, but it's actually not too inconvenient.
+
+After this, whenever you have something that could turn into a
+commitable change, do "@kbd{hg qnew ...}". Make the @file{ChangeLog}
+right away (it can even just be a placeholder to fill in later). That
+allows you to isolate this change from other changes, even if they touch
+the same files.
+
+
+@node CVS Techniques, XEmacs from the Inside, Mercurial Techniques, Top
@chapter CVS Techniques
@cindex CVS techniques
+This section is obsolete for core XEmacs; we now use Mercurial
+@ref{Mercurial Techniques}. However these may be of some use for the
+packages, which are still in CVS for the moment.
+
@menu
* Creating a Branch::
* Merging a Branch into the Trunk::
_______________________________________________
XEmacs-Patches mailing list
XEmacs-Patches(a)xemacs.org
http://lists.xemacs.org/mailman/listinfo/xemacs-patches