| rev |
line source |
|
bos@559
|
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
|
|
bos@26
|
2
|
|
dongsheng@625
|
3 <preface id="chap.preface">
|
|
bos@559
|
4 <title>Preface</title>
|
|
bos@26
|
5
|
|
bos@559
|
6 <para>Distributed revision control is a relatively new territory,
|
|
bos@559
|
7 and has thus far grown due to people's willingness to strike out
|
|
bos@559
|
8 into ill-charted territory.</para>
|
|
bos@26
|
9
|
|
bos@559
|
10 <para>I am writing a book about distributed revision control because
|
|
bos@559
|
11 I believe that it is an important subject that deserves a field
|
|
bos@559
|
12 guide. I chose to write about Mercurial because it is the easiest
|
|
bos@559
|
13 tool to learn the terrain with, and yet it scales to the demands
|
|
bos@559
|
14 of real, challenging environments where many other revision
|
|
bos@559
|
15 control tools fail.</para>
|
|
bos@26
|
16
|
|
bos@559
|
17 <sect1>
|
|
bos@559
|
18 <title>This book is a work in progress</title>
|
|
bos@26
|
19
|
|
bos@559
|
20 <para>I am releasing this book while I am still writing it, in the
|
|
bos@559
|
21 hope that it will prove useful to others. I also hope that
|
|
bos@559
|
22 readers will contribute as they see fit.</para>
|
|
bos@200
|
23
|
|
bos@559
|
24 </sect1>
|
|
bos@559
|
25 <sect1>
|
|
bos@559
|
26 <title>About the examples in this book</title>
|
|
bos@200
|
27
|
|
bos@559
|
28 <para>This book takes an unusual approach to code samples. Every
|
|
bos@559
|
29 example is <quote>live</quote>---each one is actually the result
|
|
bos@559
|
30 of a shell script that executes the Mercurial commands you see.
|
|
bos@559
|
31 Every time an image of the book is built from its sources, all
|
|
bos@559
|
32 the example scripts are automatically run, and their current
|
|
bos@559
|
33 results compared against their expected results.</para>
|
|
bos@200
|
34
|
|
bos@559
|
35 <para>The advantage of this approach is that the examples are
|
|
bos@559
|
36 always accurate; they describe <emphasis>exactly</emphasis> the
|
|
bos@559
|
37 behaviour of the version of Mercurial that's mentioned at the
|
|
bos@559
|
38 front of the book. If I update the version of Mercurial that
|
|
bos@559
|
39 I'm documenting, and the output of some command changes, the
|
|
bos@559
|
40 build fails.</para>
|
|
bos@200
|
41
|
|
bos@559
|
42 <para>There is a small disadvantage to this approach, which is
|
|
bos@559
|
43 that the dates and times you'll see in examples tend to be
|
|
bos@559
|
44 <quote>squashed</quote> together in a way that they wouldn't be
|
|
bos@559
|
45 if the same commands were being typed by a human. Where a human
|
|
bos@559
|
46 can issue no more than one command every few seconds, with any
|
|
bos@559
|
47 resulting timestamps correspondingly spread out, my automated
|
|
bos@559
|
48 example scripts run many commands in one second.</para>
|
|
bos@200
|
49
|
|
bos@559
|
50 <para>As an instance of this, several consecutive commits in an
|
|
bos@559
|
51 example can show up as having occurred during the same second.
|
|
bos@559
|
52 You can see this occur in the <literal
|
|
bos@559
|
53 role="hg-ext">bisect</literal> example in section <xref
|
|
dongsheng@625
|
54 id="sec.undo.bisect"/>, for instance.</para>
|
|
bos@200
|
55
|
|
bos@559
|
56 <para>So when you're reading examples, don't place too much weight
|
|
bos@559
|
57 on the dates or times you see in the output of commands. But
|
|
bos@559
|
58 <emphasis>do</emphasis> be confident that the behaviour you're
|
|
bos@559
|
59 seeing is consistent and reproducible.</para>
|
|
bos@26
|
60
|
|
bos@559
|
61 </sect1>
|
|
bos@559
|
62 <sect1>
|
|
bos@559
|
63 <title>Colophon---this book is Free</title>
|
|
bos@26
|
64
|
|
bos@559
|
65 <para>This book is licensed under the Open Publication License,
|
|
bos@559
|
66 and is produced entirely using Free Software tools. It is
|
|
bos@559
|
67 typeset with \LaTeX{}; illustrations are drawn and rendered with
|
|
bos@559
|
68 <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para>
|
|
bos@26
|
69
|
|
bos@559
|
70 <para>The complete source code for this book is published as a
|
|
bos@559
|
71 Mercurial repository, at <ulink
|
|
bos@559
|
72 url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para>
|
|
bos@559
|
73
|
|
bos@559
|
74 </sect1>
|
|
bos@559
|
75 </preface>
|
|
bos@559
|
76 <!--
|
|
bos@559
|
77 local variables:
|
|
bos@559
|
78 sgml-parent-document: ("00book.xml" "book" "preface")
|
|
bos@559
|
79 end:
|
|
bos@559
|
80 -->
|
