1. docker
  2. Commit 77f840fb8bc679b8d0c3eb4ce7f443f904b7f9ac
Browse code

Proposal for an improved project structure.

Note: this deprecates the fine-grained, high-overlap cascading MAINTAINERS files,
and replaces them with a single top-level file, using a new structure:

* More coarse grained subsystems with dedicated teams of maintainers
* Core maintainers with a better-defined role and a wider scope (if it's
not in a subsystem, it's up to the core maintainers to figure it out)
* Architects
* Operators

This is work in progress, the goal is to start a conversation

Signed-off-by: Solomon Hykes <solomon@docker.com>
Signed-off-by: Erik Hollensbe <github@hollensbe.org>
Signed-off-by: Arnaud Porterie <arnaud.porterie@docker.com>
Signed-off-by: Tibor Vass <teabee89@gmail.com>
Signed-off-by: Victor Vieux <vieux@docker.com>
Signed-off-by: Vincent Batts <vbatts@redhat.com>

Solomon Hykes authored on 2014/11/10 04:59:57
Showing 3 changed files
MAINTAINERS
History View file @ 77f840f
... ... 
@@ -1,9 +1,485 @@
1 
-Solomon Hykes <solomon@docker.com> (@shykes)
2 
-Victor Vieux <vieux@docker.com> (@vieux)
3 
-Michael Crosby <michael@crosbymichael.com> (@crosbymichael)
4 
-.mailmap: Tianon Gravi <admwiggin@gmail.com> (@tianon)
5 
-.travis.yml: Tianon Gravi <admwiggin@gmail.com> (@tianon)
6 
-AUTHORS: Tianon Gravi <admwiggin@gmail.com> (@tianon)
7 
-Dockerfile: Tianon Gravi <admwiggin@gmail.com> (@tianon)
8 
-Makefile: Tianon Gravi <admwiggin@gmail.com> (@tianon)
9 
-.dockerignore: Tianon Gravi <admwiggin@gmail.com> (@tianon)
1 
+# Docker maintainers file
2 
+#
3 
+# This file describes who runs the Docker project and how.
4 
+# This is a living document - if you see something out of date or missing,
5 
+# speak up!
6 
+#
7 
+# It is structured to be consumable by both humans and programs.
8 
+# To extract its contents programmatically, use any TOML-compliant
9 
+# parser.
10 
+
11 
+[Rules]
12 
+
13 
+	[Rules.maintainers]
14 
+
15 
+	title = "What is a maintainer?"
16 
+
17 
+	text = """
18 
+There are different types of maintainers, with different responsibilities, but
19 
+all maintainers have 3 things in common:
20 
+
21 
+1) They share responsibility in the project's success.
22 
+2) They have made a long-term, recurring time investment to improve the project.
23 
+3) They spend that time doing whatever needs to be done, not necessarily what
24 
+is the most interesting or fun.
25 
+
26 
+Maintainers are often under-appreciated, because their work is harder to appreciate.
27 
+It's easy to appreciate a really cool and technically advanced feature. It's harder
28 
+to appreciate the absence of bugs, the slow but steady improvement in stability,
29 
+or the reliability of a release process. But those things distinguish a good
30 
+project from a great one.
31 
+"""
32 
+
33 
+	[Rules.bdfl]
34 
+
35 
+		title = "The Benevolent dictator for life (BDFL)"
36 
+
37 
+		text = """
38 
+Docker follows the timeless, highly efficient and totally unfair system
39 
+known as [Benevolent dictator for
40 
+life](http://en.wikipedia.org/wiki/Benevolent_Dictator_for_Life), with
41 
+yours truly, Solomon Hykes, in the role of BDFL. This means that all
42 
+decisions are made, by default, by Solomon. Since making every decision
43 
+myself would be highly un-scalable, in practice decisions are spread
44 
+across multiple maintainers.
45 
+
46 
+Ideally, the BDFL role is like the Queen of England: awesome crown, but not
47 
+an actual operational role day-to-day. The real job of a BDFL is to NEVER GO AWAY.
48 
+Every other rule can change, perhaps drastically so, but the BDFL will always
49 
+be there, preserving the philosophy and principles of the project, and keeping
50 
+ultimate authority over its fate. This gives us great flexibility in experimenting
51 
+with various governance models, knowing that we can always press the "reset" button
52 
+without fear of fragmentation or deadlock. See the US congress for a counter-example.
53 
+
54 
+BDFL daily routine:
55 
+
56 
+* Is the project governance stuck in a deadlock or irreversibly fragmented?
57 
+	* If yes: refactor the project governance
58 
+* Are there issues or conflicts escalated by core?
59 
+	* If yes: resolve them
60 
+* Go back to polishing that crown.
61 
+"""
62 
+
63 
+	[Rules.decisions]
64 
+
65 
+		title = "How are decisions made?"
66 
+
67 
+		text = """
68 
+Short answer: EVERYTHING IS A PULL REQUEST.
69 
+
70 
+Docker is an open-source project with an open design philosophy. This
71 
+means that the repository is the source of truth for EVERY aspect of the
72 
+project, including its philosophy, design, road map, and APIs. *If it's
73 
+part of the project, it's in the repo. If it's in the repo, it's part of
74 
+the project.*
75 
+
76 
+As a result, all decisions can be expressed as changes to the
77 
+repository. An implementation change is a change to the source code. An
78 
+API change is a change to the API specification. A philosophy change is
79 
+a change to the philosophy manifesto, and so on.
80 
+
81 
+All decisions affecting Docker, big and small, follow the same 3 steps:
82 
+
83 
+* Step 1: Open a pull request. Anyone can do this.
84 
+
85 
+* Step 2: Discuss the pull request. Anyone can do this.
86 
+
87 
+* Step 3: Merge or refuse the pull request. Who does this depends on the nature
88 
+of the pull request and which areas of the project it affects. See *review flow*
89 
+for details.
90 
+
91 
+Because Docker is such a large and active project, it's important for everyone to know
92 
+who is responsible for deciding what. That is determined by a precise set of rules.
93 
+
94 
+* For every *decision* in the project, the rules should designate, in a deterministic way,
95 
+who should *decide*.
96 
+
97 
+* For every *problem* in the project, the rules should designate, in a deterministic way,
98 
+who should be responsible for *fixing* it.
99 
+
100 
+* For every *question* in the project, the rules should designate, in a deterministic way,
101 
+who should be expected to have the *answer*.
102 
+"""
103 
+
104 
+	[Rules.review]
105 
+
106 
+		title = "Review flow"
107 
+
108 
+		text = """
109 
+Pull requests should be processed according to the following flow:
110 
+
111 
+* For each subsystem affected by the change, the maintainers of the subsystem must approve or refuse it.
112 
+It is the responsibility of the subsystem maintainers to process patches affecting them in a timely
113 
+manner.
114 
+
115 
+* If the change affects areas of the code which are not part of a subsystem,
116 
+or if subsystem maintainers are unable to reach a timely decision, it must be approved by
117 
+the core maintainers.
118 
+
119 
+* If the change affects the UI or public APIs, or if it represents a major change in architecture,
120 
+the architects must approve or refuse it.
121 
+
122 
+* If the change affects the operations of the project, it must be approved or rejected by
123 
+the relevant operators.
124 
+
125 
+* If the change affects the governance, philosophy, goals or principles of the project,
126 
+it must be approved by BDFL.
127 
+"""
128 
+
129 
+	[Rules.DCO]
130 
+
131 
+	title = "Helping contributors with the DCO"
132 
+
133 
+	text = """
134 
+The [DCO or `Sign your work`](
135 
+https://github.com/docker/docker/blob/master/CONTRIBUTING.md#sign-your-work)
136 
+requirement is not intended as a roadblock or speed bump.
137 
+
138 
+Some Docker contributors are not as familiar with `git`, or have used a web based
139 
+editor, and thus asking them to `git commit --amend -s` is not the best way forward.
140 
+
141 
+In this case, maintainers can update the commits based on clause (c) of the DCO. The
142 
+most trivial way for a contributor to allow the maintainer to do this, is to add
143 
+a DCO signature in a Pull Requests's comment, or a maintainer can simply note that
144 
+the change is sufficiently trivial that it does not substantivly change the existing
145 
+contribution - i.e., a spelling change.
146 
+
147 
+When you add someone's DCO, please also add your own to keep a log.
148 
+"""
149 
+
150 
+	[Rules.holiday]
151 
+
152 
+	title = "I'm a maintainer, and I'm going on holiday"
153 
+
154 
+	text = """
155 
+Please let your co-maintainers and other contributors know by raising a pull
156 
+request that comments out your `MAINTAINERS` file entry using a `#`.
157 
+"""
158 
+
159 
+	[Rules."no direct push"]
160 
+
161 
+	title = "I'm a maintainer. Should I make pull requests too?"
162 
+
163 
+	text = """
164 
+Yes. Nobody should ever push to master directly. All changes should be
165 
+made through a pull request.
166 
+"""
167 
+
168 
+	[Rules.meta]
169 
+
170 
+	title = "How is this process changed?"
171 
+
172 
+	text = "Just like everything else: by making a pull request :)"
173 
+
174 
+# Current project organization
175 
+[Org]
176 
+
177 
+	bdfl = "shykes"
178 
+
179 
+	# The chief architect is responsible for the overall integrity of the technical architecture
180 
+	# across all subsystems, and the consistency of APIs and UI.
181 
+	#
182 
+	# Changes to UI, public APIs and overall architecture (for example a plugin system) must
183 
+	# be approved by the chief architect.
184 
+	"Chief Architect" = "shykes"
185 
+
186 
+	# The Chief Operator is responsible for the day-to-day operations of the project including:
187 
+	# - facilitating communications amongst all the contributors;
188 
+	# - tracking release schedules;
189 
+	# - managing the relationship with downstream distributions and upstream dependencies;
190 
+	# - helping new contributors to get involved and become successful contributors and maintainers
191 
+	#
192 
+	# The role is also responsible for managing and measuring the success of the overall project
193 
+	# and ensuring it is governed properly working in concert with the Docker Governance Advisory Board (DGAB).
194 
+	#
195 
+	# We are currently looking for a chief operator. Get in touch if you're interested!
196 
+	#
197 
+	"Chief Operator" = "spf13"
198 
+
199 
+	[Org.Operators]
200 
+
201 
+	# The operators make sure the trains run on time. They are responsible for overall operations
202 
+	# of the project. This includes facilitating communication between all the participants; helping
203 
+	# newcomers get involved and become successful contributors and maintainers; tracking the schedule
204 
+	# of releases; managing the relationship with downstream distributions and upstream dependencies;
205 
+	# define measures of success for the project and measure progress; Devise and implement tools and
206 
+	# processes which make contributors and maintainers happier and more efficient.
207 
+
208 
+
209 
+		[Org.Operators.security]
210 
+
211 
+			people = [
212 
+				"erw"
213 
+			]
214 
+
215 
+		[Org.Operators."monthly meetings"]
216 
+
217 
+			people = [
218 
+				"sven",
219 
+				"tianon"
220 
+			]
221 
+
222 
+		[Org.Operators.infrastructure]
223 
+
224 
+			people = [
225 
+				"jess",
226 
+				"crosbymichael"
227 
+			]
228 
+
229 
+	# The chief maintainer is responsible for all aspects of quality for the project including
230 
+	# code reviews, usability, stability, security, performance, etc.
231 
+	# The most important function of the chief maintainer is to lead by example. On the first
232 
+	# day of a new maintainer, the best advice should be "follow the C.M.'s example and you'll
233 
+	# be fine".
234 
+	"Chief Maintainer" = "crosbymichael"
235 
+
236 
+	[Org."Core maintainers"]
237 
+
238 
+	# The Core maintainers are the ghostbusters of the project: when there's a problem others
239 
+	# can't solve, they show up and fix it with bizarre devices and weaponry.
240 
+	# They have final say on technical implementation and coding style.
241 
+	# They are ultimately responsible for quality in all its forms: usability polish,
242 
+	# bugfixes, performance, stability, etc. When ownership  can cleanly be passed to
243 
+	# a subsystem, they are responsible for doing so and holding the
244 
+	# subsystem maintainers accountable. If ownership is unclear, they are the de facto owners.
245 
+
246 
+	# For each release (including minor releases), a "release captain" is assigned from the
247 
+	# pool of core maintainers. Rotation is encouraged across all maintainers, to ensure
248 
+	# the release process is clear and up-to-date.
249 
+	#
250 
+	# It is common for core maintainers to "branch out" to join or start a subsystem.
251 
+
252 
+
253 
+
254 
+		people = [
255 
+			"unclejack",
256 
+			"crosbymichael",
257 
+			"erikh",
258 
+			"icecrime",
259 
+			"jfrazelle",
260 
+			"lk4d4",
261 
+			"tibor",
262 
+			"vbatts",
263 
+			"vieux",
264 
+			"vish"
265 
+		]
266 
+
267 
+
268 
+	[Org.Subsystems]
269 
+
270 
+	# As the project grows, it gets separated into well-defined subsystems. Each subsystem
271 
+	# has a dedicated group of maintainers, which are dedicated to that subsytem and responsible
272 
+	# for its quality.
273 
+	# This "cellular division" is the primary mechanism for scaling maintenance of the project as it grows.
274 
+	#
275 
+	# The maintainers of each subsytem are responsible for:
276 
+	#
277 
+	# 1. Exposing a clear road map for improving their subsystem.
278 
+	# 2. Deliver prompt feedback and decisions on pull requests affecting their subsystem.
279 
+	# 3. Be available to anyone with questions, bug reports, criticism etc.
280 
+	#   on their component. This includes IRC, GitHub requests and the mailing
281 
+	#   list.
282 
+	# 4. Make sure their subsystem respects the philosophy, design and
283 
+	#   road map of the project.
284 
+	#
285 
+	# #### How to review patches to your subsystem
286 
+	#
287 
+	# Accepting pull requests:
288 
+	#
289 
+	#   - If the pull request appears to be ready to merge, give it a `LGTM`, which
290 
+	#     stands for "Looks Good To Me".
291 
+	#   - If the pull request has some small problems that need to be changed, make
292 
+	#     a comment adressing the issues.
293 
+	#   - If the changes needed to a PR are small, you can add a "LGTM once the
294 
+	#     following comments are adressed..." this will reduce needless back and
295 
+	#     forth.
296 
+	#   - If the PR only needs a few changes before being merged, any MAINTAINER can
297 
+	#     make a replacement PR that incorporates the existing commits and fixes the
298 
+	#     problems before a fast track merge.
299 
+	#
300 
+	# Closing pull requests:
301 
+	#
302 
+	#   - If a PR appears to be abandoned, after having attempted to contact the
303 
+	#     original contributor, then a replacement PR may be made.  Once the
304 
+	#     replacement PR is made, any contributor may close the original one.
305 
+	#   - If you are not sure if the pull request implements a good feature or you
306 
+	#     do not understand the purpose of the PR, ask the contributor to provide
307 
+	#     more documentation.  If the contributor is not able to adequately explain
308 
+	#     the purpose of the PR, the PR may be closed by any MAINTAINER.
309 
+	#   - If a MAINTAINER feels that the pull request is sufficiently architecturally
310 
+	#     flawed, or if the pull request needs significantly more design discussion
311 
+	#     before being considered, the MAINTAINER should close the pull request with
312 
+	#     a short explanation of what discussion still needs to be had.  It is
313 
+	#     important not to leave such pull requests open, as this will waste both the
314 
+	#     MAINTAINER's time and the contributor's time.  It is not good to string a
315 
+	#     contributor on for weeks or months, having them make many changes to a PR
316 
+	#     that will eventually be rejected.
317 
+
318 
+		[Org.Subsystems.Documentation]
319 
+
320 
+			people = [
321 
+				"fredlf",
322 
+				"james",
323 
+				"sven",
324 
+			]
325 
+
326 
+		[Org.Subsystems.libcontainer]
327 
+
328 
+			people = [
329 
+				"crosbymichael",
330 
+				"vmarmol",
331 
+				"mpatel",
332 
+				"jnagal",
333 
+				"lk4d4"
334 
+			]
335 
+
336 
+		[Org.Subsystems.registry]
337 
+
338 
+			people = [
339 
+				"dmp42",
340 
+				"vbatts",
341 
+				"joffrey",
342 
+				"samalba"
343 
+			]
344 
+
345 
+		[Org.Subsystems."build tools"]
346 
+
347 
+			people = [
348 
+				"shykes",
349 
+				"tianon"
350 
+			]
351 
+
352 
+		[Org.Subsystem."remote api"]
353 
+
354 
+			people = [
355 
+				"vieux"
356 
+			]
357 
+
358 
+		[Org.Subsystem.swarm]
359 
+
360 
+			people = [
361 
+				"aluzzardi",
362 
+				"vieux"
363 
+			]
364 
+
365 
+		[Org.Subsystem.machine]
366 
+
367 
+			people = [
368 
+				"bfirsh",
369 
+				"ehazlett"
370 
+			]
371 
+
372 
+		[Org.Subsystem.compose]
373 
+
374 
+			people = [
375 
+				"aanand"
376 
+			]
377 
+
378 
+
379 
+[people]
380 
+
381 
+# A reference list of all people associated with the project.
382 
+# All other sections should refer to people by their canonical key
383 
+# in the people section.
384 
+
385 
+	# ADD YOURSELF HERE IN ALPHABETICAL ORDER
386 
+
387 
+	[people.aanand]
388 
+	Name = "Aanand Prasad"
389 
+	Email = "aanand@docker.com"
390 
+	Github = "aanand"
391 
+
392 
+	[people.aluzzardi]
393 
+	Name = "Andrea Luzzardi"
394 
+	Email = "aluzzardi@docker.com"
395 
+	Github = "aluzzardi"
396 
+
397 
+	[people.bfirsh]
398 
+	Name = "Ben Firshman"
399 
+	Email = "ben@firshman.co.uk"
400 
+	Github = "bfirsh"
401 
+
402 
+	[people.ehazlett]
403 
+	Name = "Evan Hazlett"
404 
+	Email = "ejhazlett@gmail.com"
405 
+	Github = "ehazlett"
406 
+
407 
+	[people.erikh]
408 
+	Name = "Erik Hollensbe"
409 
+	Email = "erik@docker.com"
410 
+	Github = "erikh"
411 
+
412 
+	[people.erw]
413 
+	Name = "Eric Windisch"
414 
+	Email = "eric@windisch.us"
415 
+	Github = "ewindisch"
416 
+
417 
+	[people.icecrime]
418 
+	Name = "Arnaud Porterie"
419 
+	Email = "arnaud@docker.com"
420 
+	Github = "icecrime"
421 
+
422 
+	[people.jfrazelle]
423 
+	Name = "Jessie Frazelle"
424 
+	Email = "jess@docker.com"
425 
+	Github = "jfrazelle"
426 
+
427 
+	[people.lk4d4]
428 
+	Name = "Alexander Morozov"
429 
+	Email = "lk4d4@docker.com"
430 
+	Github = "lk4d4"
431 
+
432 
+	[people.shykes]
433 
+	Name = "Solomon Hykes"
434 
+	Email = "solomon@docker.com"
435 
+	Github = "shykes"
436 
+
437 
+	[people.sven]
438 
+	Name = "Sven Dowideit"
439 
+	Email = "SvenDowideit@home.org.au"
440 
+	GitHub = "SvenDowideit"
441 
+
442 
+	[people.tibor]
443 
+	Name = "Tibor Vass"
444 
+	Email = "tibor@docker.com"
445 
+	Github = "tiborvass"
446 
+
447 
+	[people.vbatts]
448 
+	Name = "Vincent Batts"
449 
+	Email = "vbatts@redhat.com"
450 
+	Github = "vbatts"
451 
+
452 
+	[people.vieux]
453 
+	Name = "Victor Vieux"
454 
+	Email = "vieux@docker.com"
455 
+	Github = "vieux"
456 
+
457 
+	[people.vmarmol]
458 
+	Name = "Victor Marmol"
459 
+	Email = "vmarmol@google.com"
460 
+	Github = "vmarmol"
461 
+
462 
+	[people.jnagal]
463 
+	Name = "Rohit Jnagal"
464 
+	Email = "jnagal@google.com"
465 
+	Github = "rjnagal"
466 
+
467 
+	[people.mpatel]
468 
+	Name = "Mrunal Patel"
469 
+	Email = "mpatel@redhat.com"
470 
+	Github = "mrunalp"
471 
+
472 
+	[people.unclejack]
473 
+	Name = "Cristian Staretu"
474 
+	Email = "cristian.staretu@gmail.com"
475 
+	Github = "unclejack"
476 
+
477 
+	[people.vish]
478 
+	Name = "Vishnu Kannan"
479 
+	Email = "vishnuk@google.com"
480 
+	Github = "vishh"
481 
+
482 
+	[people.spf13]
483 
+	Name = "Steve Francia"
484 
+	Email = "steve.francia@gmail.com"
485 
+	Github = "spf13"
README.md
History View file @ 77f840f
... ... 
@@ -195,6 +195,14 @@ Don't know how to use that super cool new feature in the master build? Check
195 195 
 out the master docs at
196 196 
 [docs.master.dockerproject.com](http://docs.master.dockerproject.com).
197 197
198 
+How the project is run
199 
+======================
200 
+
201 
+Docker is a very, very active project. If you want to learn more about how it is run,
202 
+or want to get more involved, the best place to start is [the project directory](https://github.com/docker/docker/tree/project).
203 
+
204 
+We are always open to suggestions on process improvements, and are always looking for more maintainers.
205 
+
198 206 
 ### Legal
199 207
200 208 
 *Brought to you courtesy of our legal counsel. For more context,
project/MAINTAINERS.md
History View file @ 77f840f
201 209 
deleted file mode 100644
... ... 
@@ -1,147 +0,0 @@
1 
-# The Docker Maintainer manual
2 
-
3 
-## Introduction
4 
-
5 
-Dear maintainer. Thank you for investing the time and energy to help
6 
-make Docker as useful as possible. Maintaining a project is difficult,
7 
-sometimes unrewarding work. Sure, you will get to contribute cool
8 
-features to the project. But most of your time will be spent reviewing,
9 
-cleaning up, documenting, answering questions, and justifying design
10 
-decisions - while everyone has all the fun! But remember - the quality
11 
-of the maintainers' work is what distinguishes the good projects from
12 
-the great. So please be proud of your work, even the unglamourous parts,
13 
-and encourage a culture of appreciation and respect for *every* aspect
14 
-of improving the project - not just the hot new features.
15 
-
16 
-This document is a manual for maintainers old and new. It explains what
17 
-is expected of maintainers, how they should work, and what tools are
18 
-available to them.
19 
-
20 
-This is a living document - if you see something out of date or missing,
21 
-speak up!
22 
-
23 
-## What is a maintainer's responsibility?
24 
-
25 
-It is every maintainer's responsibility to:
26 
-
27 
-1. Expose a clear road map for improving their component.
28 
-2. Deliver prompt feedback and decisions on pull requests.
29 
-3. Be available to anyone with questions, bug reports, criticism etc.
30 
-  on their component. This includes IRC, GitHub requests and the mailing
31 
-  list.
32 
-4. Make sure their component respects the philosophy, design and
33 
-  road map of the project.
34 
-
35 
-## How are decisions made?
36 
-
37 
-Short answer: with pull requests to the Docker repository.
38 
-
39 
-Docker is an open-source project with an open design philosophy. This
40 
-means that the repository is the source of truth for EVERY aspect of the
41 
-project, including its philosophy, design, road map, and APIs. *If it's
42 
-part of the project, it's in the repo. If it's in the repo, it's part of
43 
-the project.*
44 
-
45 
-As a result, all decisions can be expressed as changes to the
46 
-repository. An implementation change is a change to the source code. An
47 
-API change is a change to the API specification. A philosophy change is
48 
-a change to the philosophy manifesto, and so on.
49 
-
50 
-All decisions affecting Docker, big and small, follow the same 3 steps:
51 
-
52 
-* Step 1: Open a pull request. Anyone can do this.
53 
-
54 
-* Step 2: Discuss the pull request. Anyone can do this.
55 
-
56 
-* Step 3: Accept (`LGTM`) or refuse a pull request. The relevant maintainers do
57 
-this (see below "Who decides what?")
58 
- + Accepting pull requests
59 
-  - If the pull request appears to be ready to merge, give it a `LGTM`, which
60 
-    stands for "Looks Good To Me".
61 
-  - If the pull request has some small problems that need to be changed, make
62 
-    a comment adressing the issues.
63 
-  - If the changes needed to a PR are small, you can add a "LGTM once the
64 
-    following comments are adressed..." this will reduce needless back and
65 
-    forth.
66 
-  - If the PR only needs a few changes before being merged, any MAINTAINER can
67 
-    make a replacement PR that incorporates the existing commits and fixes the
68 
-    problems before a fast track merge.
69 
- + Closing pull requests
70 
-  - If a PR appears to be abandoned, after having attempted to contact the
71 
-    original contributor, then a replacement PR may be made.  Once the
72 
-    replacement PR is made, any contributor may close the original one.
73 
-  - If you are not sure if the pull request implements a good feature or you
74 
-    do not understand the purpose of the PR, ask the contributor to provide
75 
-    more documentation.  If the contributor is not able to adequately explain
76 
-    the purpose of the PR, the PR may be closed by any MAINTAINER.
77 
-  - If a MAINTAINER feels that the pull request is sufficiently architecturally
78 
-    flawed, or if the pull request needs significantly more design discussion
79 
-    before being considered, the MAINTAINER should close the pull request with
80 
-    a short explanation of what discussion still needs to be had.  It is
81 
-    important not to leave such pull requests open, as this will waste both the
82 
-    MAINTAINER's time and the contributor's time.  It is not good to string a
83 
-    contributor on for weeks or months, having them make many changes to a PR
84 
-    that will eventually be rejected.
85 
-
86 
-## Who decides what?
87 
-
88 
-All decisions are pull requests, and the relevant maintainers make
89 
-decisions by accepting or refusing pull requests. Review and acceptance
90 
-by anyone is denoted by adding a comment in the pull request: `LGTM`.
91 
-However, only currently listed `MAINTAINERS` are counted towards the
92 
-required majority.
93 
-
94 
-Docker follows the timeless, highly efficient and totally unfair system
95 
-known as [Benevolent dictator for
96 
-life](http://en.wikipedia.org/wiki/Benevolent_Dictator_for_Life), with
97 
-yours truly, Solomon Hykes, in the role of BDFL. This means that all
98 
-decisions are made, by default, by Solomon. Since making every decision
99 
-myself would be highly un-scalable, in practice decisions are spread
100 
-across multiple maintainers.
101 
-
102 
-The relevant maintainers for a pull request can be worked out in 2 steps:
103 
-
104 
-* Step 1: Determine the subdirectories affected by the pull request. This
105 
-  might be `src/registry`, `docs/source/api`, or any other part of the repo.
106 
-
107 
-* Step 2: Find the `MAINTAINERS` file which affects this directory. If the
108 
-  directory itself does not have a `MAINTAINERS` file, work your way up
109 
-  the repo hierarchy until you find one.
110 
-
111 
-There is also a `hacks/getmaintainers.sh` script that will print out the
112 
-maintainers for a specified directory.
113 
-
114 
-### I'm a maintainer, and I'm going on holiday
115 
-
116 
-Please let your co-maintainers and other contributors know by raising a pull
117 
-request that comments out your `MAINTAINERS` file entry using a `#`.
118 
-
119 
-### I'm a maintainer. Should I make pull requests too?
120 
-
121 
-Yes. Nobody should ever push to master directly. All changes should be
122 
-made through a pull request.
123 
-
124 
-### Helping contributors with the DCO
125 
-
126 
-The [DCO or `Sign your work`](
127 
-https://github.com/docker/docker/blob/master/CONTRIBUTING.md#sign-your-work)
128 
-requirement is not intended as a roadblock or speed bump.
129 
-
130 
-Some Docker contributors are not as familiar with `git`, or have used a web based
131 
-editor, and thus asking them to `git commit --amend -s` is not the best way forward.
132 
-
133 
-In this case, maintainers can update the commits based on clause (c) of the DCO. The
134 
-most trivial way for a contributor to allow the maintainer to do this, is to add
135 
-a DCO signature in a Pull Requests's comment, or a maintainer can simply note that
136 
-the change is sufficiently trivial that it does not substantivly change the existing
137 
-contribution - i.e., a spelling change.
138 
-
139 
-When you add someone's DCO, please also add your own to keep a log.
140 
-
141 
-### Who assigns maintainers?
142 
-
143 
-Solomon has final `LGTM` approval for all pull requests to `MAINTAINERS` files.
144 
-
145 
-### How is this process changed?
146 
-
147 
-Just like everything else: by making a pull request :)