hgbook
view en/collab.tex @ 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 | |
| children | 5fc4a45c069f |
line source
1 \chapter{Collaborating with other people}
2 \label{cha:collab}
4 As a completely decentralised tool, Mercurial doesn't impose any
5 policy on how people ought to work with each other. However, if
6 you're new to distributed revision control, it helps to have some
7 tools and examples in mind when you're thinking about possible
8 workflow models.
10 \section{Collaboration models}
12 With a suitably flexible tool, making decisions about workflow is much
13 more of a social engineering challenge than a technical one.
14 Mercurial imposes few limitations on how you can structure the flow of
15 work in a project, so it's up to you and your group to set up and live
16 with a model that matches your own particular needs.
18 \subsection{Factors to keep in mind}
20 The most important aspect of any model that you must keep in mind is
21 how well it matches the needs and capabilities of the people who will
22 be using it. This might seem self-evident; even so, you still can't
23 afford to forget it for a moment.
25 I once put together a workflow model that seemed to make perfect sense
26 to me, but that caused a considerable amount of consternation and
27 strife within my development team. In spite of my attempts to explain
28 why we needed a complex set of branches, and how changes ought to flow
29 between them, a few team members revolted. Even though they were
30 smart people, they didn't want to pay attention to the constraints we
31 were operating under, or face the consequences of those constraints in
32 the details of the model that I was advocating.
34 Don't sweep foreseeable social or technical problems under the rug.
35 Whatever scheme you put into effect, you should plan for mistakes and
36 problem scenarios. Consider adding automated machinery to prevent, or
37 quickly recover from, trouble that you can anticipate. As an example,
38 if you intend to have a branch with not-for-release changes in it,
39 you'd do well to think early about the possibility that someone might
40 accidentally merge those changes into a release branch. You could
41 avoid this particular problem by writing a hook that prevents changes
42 from being merged from an inappropriate branch.
44 \subsection{Informal anarchy}
46 I wouldn't suggest an ``anything goes'' approach as something
47 sustainable, but it's a model that's easy to grasp, and it works
48 perfectly well in a few unusual situations.
50 As one example, many projects have a loose-knit group of collaborators
51 who rarely physically meet each other. Some groups like to overcome
52 the isolation of working at a distance by organising occasional
53 ``sprints''. In a sprint, a number of people get together in a single
54 location (a company's conference room, a hotel meeting room, that kind
55 of place) and spend several days more or less locked in there, hacking
56 intensely on a handful of projects.
58 A sprint is the perfect place to use the \hgcmd{serve} command, since
59 \hgcmd{serve} does not requires any fancy server infrastructure. You
60 can get started with \hgcmd{serve} in moments, by reading
61 section~\ref{sec:collab:serve} below. Then simply tell the person
62 next to you that you're running a server, send the URL to them in an
63 instant message, and you immediately have a quick-turnaround way to
64 work together. They can type your URL into their web browser and
65 quickly review your changes; or they can pull a bugfix from you and
66 verify it; or they can clone a branch containing a new feature and try
67 it out.
69 The charm, and the problem, with doing things in an ad hoc fashion
70 like this is that only people who know about your changes, and where
71 they are, can see them. Such an informal approach simply doesn't
72 scale beyond a handful people, because each individual needs to know
73 about $n$ different repositories to pull from.
75 \subsection{A single central repository}
77 For smaller projects, migrating from a centralised revision control
78 tool, perhaps the easiest way to get started is to have changes flow
79 through a single shared central repository. This is also the
80 most common ``building block'' for more ambitious workflow schemes.
82 Contributors start by cloning a copy of this repository. They can
83 pull changes from it whenever they need to, and some (perhaps all)
84 developers have permission to push a change back when they're ready
85 for other people to see it.
87 Under this model, it can still sometimes make sense for people to pull
88 changes directly from each other, without going through the central
89 repository. Consider a case in which I have a tentative bug fix, but
90 I am worried that if I were to publish it to the central repository,
91 it might subsequently break everyone else's trees as they pull it. To
92 reduce the potential for damage, I can ask you to clone my repository
93 into a temporary repository of your own and test it. This lets us put
94 off publishing the potentially unsafe change until it has had a little
95 testing.
97 In this kind of scenario, people usually use the \command{ssh}
98 protocol to securely push changes to the central repository, as
99 documented in section~\ref{sec:collab:ssh}. It's also usual to
100 publish a read-only copy of the repository over HTTP using CGI, as in
101 section~\ref{sec:collab:cgi}. Publishing over HTTP satisfies the
102 needs of people who don't have push access, and those who want to use
103 web browsers to browse the repository's history.
105 \subsection{The Linux kernel model}
107 The development of the Linux kernel has a shallow hierarchical
108 structure, surrounded by a cloud of apparent chaos. Because most
109 Linux developers use \command{git}, a distributed revision control
110 tool with capabilities similar to Mercurial, it's useful to describe
111 the way work flows in that environment; if you like the ideas, the
112 approach translates well across tools.
114 At the center of the community sits Linus Torvalds, the creator of
115 Linux. He publishes a single source repository that is considered the
116 ``authoritative'' current tree by the entire developer community.
117 Anyone can clone Linus's tree, but he is very choosy about whose trees
118 he pulls from.
120 Linus has a number of ``trusted lieutenants''. As a general rule, he
121 pulls whatever changes they publish, in most cases without even
122 reviewing those changes. Some of those lieutenants are generally
123 agreed to be ``maintainers'', responsible for specific subsystems
124 within the kernel. If a random kernel hacker wants to make a change
125 to a subsystem that they want to end up in Linus's tree, they must
126 find out who the subsystem's maintainer is, and ask that maintainer to
127 take their change. If the maintainer reviews their changes and agrees
128 to take them, they'll pass them along to Linus in due course.
130 Individual lieutenants have their own approaches to reviewing,
131 accepting, and publishing changes; and for deciding when to feed them
132 to Linus. In addition, there are several well known branches that
133 people use for different purposes. For example, a few people maintain
134 ``stable'' repositories of older versions of the kernel, to which they
135 apply critical fixes as needed.
137 This model has two notable features. The first is that it's ``pull
138 only''. You have to ask, convince, or beg another developer to take a
139 change from you, because there are no shared trees, and there's no way
140 to push changes into a tree that someone else controls.
142 The second is that it's based on reputation and acclaim. If you're an
143 unknown, Linus will probably ignore changes from you without even
144 responding. But a subsystem maintainer will probably review them, and
145 will likely take them if they pass their criteria for suitability.
146 The more ``good'' changes you contribute to a maintainer, the more
147 likely they are to trust your judgment and accept your changes. If
148 you're well-known and maintain a long-lived branch for something Linus
149 hasn't yet accepted, people with similar interests may pull your
150 changes regularly to keep up with your work.
152 Reputation and acclaim don't necessarily cross subsystem or ``people''
153 boundaries. If you're a respected but specialised storage hacker, and
154 you try to fix a networking bug, that change will receive a level of
155 scrutiny from a network maintainer comparable to a change from a
156 complete stranger.
158 To people who come from more orderly project backgrounds, the
159 comparatively chaotic Linux kernel development process often seems
160 completely insane. It's subject to the whims of individuals; people
161 make sweeping changes whenever they deem it appropriate; and the pace
162 of development is astounding. And yet Linux is a highly successful,
163 well-regarded piece of software.
165 \section{The technical side of sharing}
167 \subsection{Informal sharing with \hgcmd{serve}}
168 \label{sec:collab:serve}
170 Mercurial's \hgcmd{serve} command is wonderfully suited to small,
171 tight-knit, and fast-paced group environments. It also provides a
172 great way to get a feel for using Mercurial commands over a network.
174 Run \hgcmd{serve} inside a repository, and in under a second it will
175 bring up a specialised HTTP server; this will accept connections from
176 any client, and serve up data for that repository until you terminate
177 it. Anyone who knows the URL of the server you just started, and can
178 talk to your computer over the network, can then use a web browser or
179 Mercurial to read data from that repository. A URL for a
180 \hgcmd{serve} instance running on a laptop is likely to look something
181 like \Verb|http://my-laptop.local:8000/|.
183 The \hgcmd{serve} command is \emph{not} a general-purpose web server.
184 It can do only two things:
185 \begin{itemize}
186 \item Allow people to browse the history of the repository it's
187 serving, from their normal web browsers.
188 \item Speak Mercurial's wire protocol, so that people can
189 \hgcmd{clone} or \hgcmd{pull} changes from that repository.
190 \end{itemize}
191 In particular, \hgcmd{serve} won't allow remote users to \emph{modify}
192 your repository. It's intended for read-only use.
194 If you're getting started with Mercurial, there's nothing to prevent
195 you from using \hgcmd{serve} to serve up a repository on your own
196 computer, then use commands like \hgcmd{clone}, \hgcmd{incoming}, and
197 so on to talk to that server as if the repository was hosted remotely.
198 This can help you to quickly get acquainted with using commands on
199 network-hosted repositories.
201 \subsubsection{A few things to keep in mind}
203 Because it provides unauthenticated read access to all clients, you
204 should only use \hgcmd{serve} in an environment where you either don't
205 care, or have complete control over, who can access your network and
206 pull data from your repository.
208 The \hgcmd{serve} command knows nothing about any firewall software
209 you might have installed on your system or network. It cannot detect
210 or control your firewall software. If other people are unable to talk
211 to a running \hgcmd{serve} instance, the second thing you should do
212 (\emph{after} you make sure that they're using the correct URL) is
213 check your firewall configuration.
215 By default, \hgcmd{serve} listens for incoming connections on
216 port~8000. If another process is already listening on the port you
217 want to use, you can specify a different port to listen on using the
218 \hgopt{serve}{-p} option.
220 Normally, when \hgcmd{serve} starts, it prints no output, which can be
221 a bit unnerving. If you'd like to confirm that it is indeed running
222 correctly, and find out what URL you should send to your
223 collaborators, start it with the \hggopt{-v} option.
225 \subsection{Using \command{ssh} as a tunnel}
226 \label{sec:collab:ssh}
228 \subsection{Serving HTTP with a CGI script}
229 \label{sec:collab:cgi}
233 %%% Local Variables:
234 %%% mode: latex
235 %%% TeX-master: "00book"
236 %%% End: