1.1 --- a/en/00book.tex	Thu Mar 22 00:07:01 2007 -0700
     1.2 +++ b/en/00book.tex	Thu Mar 22 23:03:11 2007 -0700
     1.3 @@ -41,6 +41,7 @@
     1.4  \include{tour-merge}
     1.5  \include{concepts}
     1.6  \include{daily}
     1.7 +\include{collab}
     1.8  \include{filenames}
     1.9  \include{undo}
    1.10  \include{hook}

     2.1 --- a/en/Makefile	Thu Mar 22 00:07:01 2007 -0700
     2.2 +++ b/en/Makefile	Thu Mar 22 23:03:11 2007 -0700
     2.3 @@ -8,6 +8,7 @@
     2.4  	99defs.tex \
     2.5  	build_id.tex \
     2.6  	cmdref.tex \
     2.7 +	collab.tex \
     2.8  	concepts.tex \
     2.9  	daily.tex \
    2.10  	filenames.tex \
    2.11 @@ -78,6 +79,7 @@
    2.12  	tour-merge-conflict
    2.13  
    2.14  dist-sources := \
    2.15 +	../html/hgicon.png \
    2.16  	../html/index.html.var \
    2.17  	../html/index.en.html
    2.18  

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/en/collab.tex	Thu Mar 22 23:03:11 2007 -0700
     3.3 @@ -0,0 +1,236 @@
     3.4 +\chapter{Collaborating with other people}
     3.5 +\label{cha:collab}
     3.6 +
     3.7 +As a completely decentralised tool, Mercurial doesn't impose any
     3.8 +policy on how people ought to work with each other.  However, if
     3.9 +you're new to distributed revision control, it helps to have some
    3.10 +tools and examples in mind when you're thinking about possible
    3.11 +workflow models.
    3.12 +
    3.13 +\section{Collaboration models}
    3.14 +
    3.15 +With a suitably flexible tool, making decisions about workflow is much
    3.16 +more of a social engineering challenge than a technical one.
    3.17 +Mercurial imposes few limitations on how you can structure the flow of
    3.18 +work in a project, so it's up to you and your group to set up and live
    3.19 +with a model that matches your own particular needs.
    3.20 +
    3.21 +\subsection{Factors to keep in mind}
    3.22 +
    3.23 +The most important aspect of any model that you must keep in mind is
    3.24 +how well it matches the needs and capabilities of the people who will
    3.25 +be using it.  This might seem self-evident; even so, you still can't
    3.26 +afford to forget it for a moment.
    3.27 +
    3.28 +I once put together a workflow model that seemed to make perfect sense
    3.29 +to me, but that caused a considerable amount of consternation and
    3.30 +strife within my development team.  In spite of my attempts to explain
    3.31 +why we needed a complex set of branches, and how changes ought to flow
    3.32 +between them, a few team members revolted.  Even though they were
    3.33 +smart people, they didn't want to pay attention to the constraints we
    3.34 +were operating under, or face the consequences of those constraints in
    3.35 +the details of the model that I was advocating.
    3.36 +
    3.37 +Don't sweep foreseeable social or technical problems under the rug.
    3.38 +Whatever scheme you put into effect, you should plan for mistakes and
    3.39 +problem scenarios.  Consider adding automated machinery to prevent, or
    3.40 +quickly recover from, trouble that you can anticipate.  As an example,
    3.41 +if you intend to have a branch with not-for-release changes in it,
    3.42 +you'd do well to think early about the possibility that someone might
    3.43 +accidentally merge those changes into a release branch.  You could
    3.44 +avoid this particular problem by writing a hook that prevents changes
    3.45 +from being merged from an inappropriate branch.
    3.46 +
    3.47 +\subsection{Informal anarchy}
    3.48 +
    3.49 +I wouldn't suggest an ``anything goes'' approach as something
    3.50 +sustainable, but it's a model that's easy to grasp, and it works
    3.51 +perfectly well in a few unusual situations.
    3.52 +
    3.53 +As one example, many projects have a loose-knit group of collaborators
    3.54 +who rarely physically meet each other.  Some groups like to overcome
    3.55 +the isolation of working at a distance by organising occasional
    3.56 +``sprints''.  In a sprint, a number of people get together in a single
    3.57 +location (a company's conference room, a hotel meeting room, that kind
    3.58 +of place) and spend several days more or less locked in there, hacking
    3.59 +intensely on a handful of projects.
    3.60 +
    3.61 +A sprint is the perfect place to use the \hgcmd{serve} command, since
    3.62 +\hgcmd{serve} does not requires any fancy server infrastructure.  You
    3.63 +can get started with \hgcmd{serve} in moments, by reading
    3.64 +section~\ref{sec:collab:serve} below.  Then simply tell the person
    3.65 +next to you that you're running a server, send the URL to them in an
    3.66 +instant message, and you immediately have a quick-turnaround way to
    3.67 +work together.  They can type your URL into their web browser and
    3.68 +quickly review your changes; or they can pull a bugfix from you and
    3.69 +verify it; or they can clone a branch containing a new feature and try
    3.70 +it out.
    3.71 +
    3.72 +The charm, and the problem, with doing things in an ad hoc fashion
    3.73 +like this is that only people who know about your changes, and where
    3.74 +they are, can see them.  Such an informal approach simply doesn't
    3.75 +scale beyond a handful people, because each individual needs to know
    3.76 +about $n$ different repositories to pull from.
    3.77 +
    3.78 +\subsection{A single central repository}
    3.79 +
    3.80 +For smaller projects, migrating from a centralised revision control
    3.81 +tool, perhaps the easiest way to get started is to have changes flow
    3.82 +through a single shared central repository.  This is also the
    3.83 +most common ``building block'' for more ambitious workflow schemes.
    3.84 +
    3.85 +Contributors start by cloning a copy of this repository.  They can
    3.86 +pull changes from it whenever they need to, and some (perhaps all)
    3.87 +developers have permission to push a change back when they're ready
    3.88 +for other people to see it.
    3.89 +
    3.90 +Under this model, it can still sometimes make sense for people to pull
    3.91 +changes directly from each other, without going through the central
    3.92 +repository.  Consider a case in which I have a tentative bug fix, but
    3.93 +I am worried that if I were to publish it to the central repository,
    3.94 +it might subsequently break everyone else's trees as they pull it.  To
    3.95 +reduce the potential for damage, I can ask you to clone my repository
    3.96 +into a temporary repository of your own and test it.  This lets us put
    3.97 +off publishing the potentially unsafe change until it has had a little
    3.98 +testing.
    3.99 +
   3.100 +In this kind of scenario, people usually use the \command{ssh}
   3.101 +protocol to securely push changes to the central repository, as
   3.102 +documented in section~\ref{sec:collab:ssh}.  It's also usual to
   3.103 +publish a read-only copy of the repository over HTTP using CGI, as in
   3.104 +section~\ref{sec:collab:cgi}.  Publishing over HTTP satisfies the
   3.105 +needs of people who don't have push access, and those who want to use
   3.106 +web browsers to browse the repository's history.
   3.107 +
   3.108 +\subsection{The Linux kernel model}
   3.109 +
   3.110 +The development of the Linux kernel has a shallow hierarchical
   3.111 +structure, surrounded by a cloud of apparent chaos.  Because most
   3.112 +Linux developers use \command{git}, a distributed revision control
   3.113 +tool with capabilities similar to Mercurial, it's useful to describe
   3.114 +the way work flows in that environment; if you like the ideas, the
   3.115 +approach translates well across tools.
   3.116 +
   3.117 +At the center of the community sits Linus Torvalds, the creator of
   3.118 +Linux.  He publishes a single source repository that is considered the
   3.119 +``authoritative'' current tree by the entire developer community.
   3.120 +Anyone can clone Linus's tree, but he is very choosy about whose trees
   3.121 +he pulls from.
   3.122 +
   3.123 +Linus has a number of ``trusted lieutenants''.  As a general rule, he
   3.124 +pulls whatever changes they publish, in most cases without even
   3.125 +reviewing those changes.  Some of those lieutenants are generally
   3.126 +agreed to be ``maintainers'', responsible for specific subsystems
   3.127 +within the kernel.  If a random kernel hacker wants to make a change
   3.128 +to a subsystem that they want to end up in Linus's tree, they must
   3.129 +find out who the subsystem's maintainer is, and ask that maintainer to
   3.130 +take their change.  If the maintainer reviews their changes and agrees
   3.131 +to take them, they'll pass them along to Linus in due course.
   3.132 +
   3.133 +Individual lieutenants have their own approaches to reviewing,
   3.134 +accepting, and publishing changes; and for deciding when to feed them
   3.135 +to Linus.  In addition, there are several well known branches that
   3.136 +people use for different purposes.  For example, a few people maintain
   3.137 +``stable'' repositories of older versions of the kernel, to which they
   3.138 +apply critical fixes as needed.
   3.139 +
   3.140 +This model has two notable features.  The first is that it's ``pull
   3.141 +only''.  You have to ask, convince, or beg another developer to take a
   3.142 +change from you, because there are no shared trees, and there's no way
   3.143 +to push changes into a tree that someone else controls.
   3.144 +
   3.145 +The second is that it's based on reputation and acclaim.  If you're an
   3.146 +unknown, Linus will probably ignore changes from you without even
   3.147 +responding.  But a subsystem maintainer will probably review them, and
   3.148 +will likely take them if they pass their criteria for suitability.
   3.149 +The more ``good'' changes you contribute to a maintainer, the more
   3.150 +likely they are to trust your judgment and accept your changes.  If
   3.151 +you're well-known and maintain a long-lived branch for something Linus
   3.152 +hasn't yet accepted, people with similar interests may pull your
   3.153 +changes regularly to keep up with your work.
   3.154 +
   3.155 +Reputation and acclaim don't necessarily cross subsystem or ``people''
   3.156 +boundaries.  If you're a respected but specialised storage hacker, and
   3.157 +you try to fix a networking bug, that change will receive a level of
   3.158 +scrutiny from a network maintainer comparable to a change from a
   3.159 +complete stranger.
   3.160 +
   3.161 +To people who come from more orderly project backgrounds, the
   3.162 +comparatively chaotic Linux kernel development process often seems
   3.163 +completely insane.  It's subject to the whims of individuals; people
   3.164 +make sweeping changes whenever they deem it appropriate; and the pace
   3.165 +of development is astounding.  And yet Linux is a highly successful,
   3.166 +well-regarded piece of software.
   3.167 +
   3.168 +\section{The technical side of sharing}
   3.169 +
   3.170 +\subsection{Informal sharing with \hgcmd{serve}}
   3.171 +\label{sec:collab:serve}
   3.172 +
   3.173 +Mercurial's \hgcmd{serve} command is wonderfully suited to small,
   3.174 +tight-knit, and fast-paced group environments.  It also provides a
   3.175 +great way to get a feel for using Mercurial commands over a network.
   3.176 +
   3.177 +Run \hgcmd{serve} inside a repository, and in under a second it will
   3.178 +bring up a specialised HTTP server; this will accept connections from
   3.179 +any client, and serve up data for that repository until you terminate
   3.180 +it.  Anyone who knows the URL of the server you just started, and can
   3.181 +talk to your computer over the network, can then use a web browser or
   3.182 +Mercurial to read data from that repository.  A URL for a
   3.183 +\hgcmd{serve} instance running on a laptop is likely to look something
   3.184 +like \Verb|http://my-laptop.local:8000/|.
   3.185 +
   3.186 +The \hgcmd{serve} command is \emph{not} a general-purpose web server.
   3.187 +It can do only two things:
   3.188 +\begin{itemize}
   3.189 +\item Allow people to browse the history of the repository it's
   3.190 +  serving, from their normal web browsers.
   3.191 +\item Speak Mercurial's wire protocol, so that people can
   3.192 +  \hgcmd{clone} or \hgcmd{pull} changes from that repository.
   3.193 +\end{itemize}
   3.194 +In particular, \hgcmd{serve} won't allow remote users to \emph{modify}
   3.195 +your repository.  It's intended for read-only use.
   3.196 +
   3.197 +If you're getting started with Mercurial, there's nothing to prevent
   3.198 +you from using \hgcmd{serve} to serve up a repository on your own
   3.199 +computer, then use commands like \hgcmd{clone}, \hgcmd{incoming}, and
   3.200 +so on to talk to that server as if the repository was hosted remotely.
   3.201 +This can help you to quickly get acquainted with using commands on
   3.202 +network-hosted repositories.
   3.203 +
   3.204 +\subsubsection{A few things to keep in mind}
   3.205 +
   3.206 +Because it provides unauthenticated read access to all clients, you
   3.207 +should only use \hgcmd{serve} in an environment where you either don't
   3.208 +care, or have complete control over, who can access your network and
   3.209 +pull data from your repository.
   3.210 +
   3.211 +The \hgcmd{serve} command knows nothing about any firewall software
   3.212 +you might have installed on your system or network.  It cannot detect
   3.213 +or control your firewall software.  If other people are unable to talk
   3.214 +to a running \hgcmd{serve} instance, the second thing you should do
   3.215 +(\emph{after} you make sure that they're using the correct URL) is
   3.216 +check your firewall configuration.
   3.217 +
   3.218 +By default, \hgcmd{serve} listens for incoming connections on
   3.219 +port~8000.  If another process is already listening on the port you
   3.220 +want to use, you can specify a different port to listen on using the
   3.221 +\hgopt{serve}{-p} option.
   3.222 +
   3.223 +Normally, when \hgcmd{serve} starts, it prints no output, which can be
   3.224 +a bit unnerving.  If you'd like to confirm that it is indeed running
   3.225 +correctly, and find out what URL you should send to your
   3.226 +collaborators, start it with the \hggopt{-v} option.
   3.227 +
   3.228 +\subsection{Using \command{ssh} as a tunnel}
   3.229 +\label{sec:collab:ssh}
   3.230 +
   3.231 +\subsection{Serving HTTP with a CGI script}
   3.232 +\label{sec:collab:cgi}
   3.233 +
   3.234 +
   3.235 +
   3.236 +%%% Local Variables: 
   3.237 +%%% mode: latex
   3.238 +%%% TeX-master: "00book"
   3.239 +%%% End: 

     4.1 Binary file html/hgicon.png has changed

     5.1 --- a/html/index.en.html	Thu Mar 22 00:07:01 2007 -0700
     5.2 +++ b/html/index.en.html	Thu Mar 22 23:03:11 2007 -0700
     5.3 @@ -3,6 +3,8 @@
     5.4  <html lang="en">
     5.5    <head>
     5.6      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
     5.7 +    <link rel="icon" href="/hgicon.png" type="image/png">
     5.8 +    <meta name="robots" content="index,follow">
     5.9      <title>Distributed revision control with Mercurial</title>
    5.10    </head>
    5.11