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