hgbook
changeset 159:7355af913937
First steps on collaboration chapter.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu Mar 22 23:03:11 2007 -0700 (2007-03-22) |
parents | d3f8aec5beff |
children | 745ff473c8c4 |
files | en/00book.tex en/Makefile en/collab.tex html/hgicon.png html/index.en.html |
line diff
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