/[gentoo]/xml/htdocs/proj/en/overlays/devguide.xml
Gentoo

Contents of /xml/htdocs/proj/en/overlays/devguide.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (show annotations) (download) (as text)
Sun Jul 30 11:05:00 2006 UTC (12 years, 6 months ago) by stuart
Branch: MAIN
File MIME type: application/xml
Added work-in-progress dev guide for o.g.o

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3
4 <guide link="/proj/en/overlays/devguide.xml">
5 <title>Gentoo Overlays: Developers' Guide</title>
6
7 <author title="Author">
8 <mail link="stuart@gentoo.org">Stuart Herbert</mail>
9 </author>
10
11 <abstract>This guide helps developers understand how to use the Gentoo
12 Overlays service.</abstract>
13
14 <license/>
15
16 <version>1.0</version>
17 <date>2006-07-29</date>
18
19 <chapter>
20 <title>Introduction</title>
21
22 <section>
23 <title>Audience</title>
24 <body>
25 <p>This document has been written for Gentoo developers and Gentoo staff members. If you are a Gentoo user, or you just want to start downloading and using overlays, please see <uri link="/proj/en/overlays/userguide.xml">the Gentoo Overlays User Guide</uri> instead.</p>
26 </body>
27 </section>
28
29 <section>
30 <title>What is overlays.gentoo.org?</title>
31 <body>
32 <p><uri link="http://overlays.gentoo.org">overlays.gentoo.org</uri> provides social workspaces to allow Gentoo projects, developers and users to collaborate together on tomorrow's Gentoo packages. We do this by hosting overlays for Gentoo projects, and overlays for Gentoo developers.</p>
33 </body>
34 </section>
35
36 <section>
37 <title>Who Can Use overlays.gentoo.org?</title>
38 <body>
39 <p>Any Gentoo project, or Gentoo developer, can have their own overlay hosted on overlays.gentoo.org, with the RSS feed from the changelog included on <uri link="http://overlays.gentoo.org">the overlays.gentoo.org homepage</uri>.</p>
40
41 <p>Any Gentoo staff member or user (ie, anyone who doesn't have write access to
42 the main Portage package tree) can download and use the contents of any hosted
43 overlay. If you choose, you can also give users write access to your
44 overlay.</p>
45 </body>
46 </section>
47
48 <section>
49 <title>What Does overlays.gentoo.org Give Me?</title>
50 <body>
51 <p>The overlays.gentoo.org service currently provides:</p>
52 <ul>
53 <li><uri link="http://trac.edgewall.com">Trac</uri> (a wiki w/ integrated subversion browser), for quickly creating and maintaining documentation about your overlay</li>
54 <li><uri link="http://subversion.tigris.org">Subversion</uri> - a centralised version control system (distributed version control systems will be supported in future)</li>
55 <li>Publishing the changelog for your overlay on <uri link="http://overlays.gentoo.org/">the o.g.o homepage</uri>, so that everyone who's interested can see what's going on</li>
56 </ul>
57
58 <p>... all hosted on secure, backed-up Gentoo infrastructure, administered by
59 <uri link="/proj/en/infrastructure">the Gentoo Infrastructure team</uri> (hardware / base OS) and <uri link="/proj/en/overlays">the Gentoo Overlays team</uri>
60 (wiki / VCS / ACLs).</p>
61
62 <p>Each overlay has separate authentication lists for Trac and for Subversion.
63 It's no problem at all to give someone write access to just Trac (e.g. for
64 writing documentation) without giving them write access to Subversion.</p>
65 </body>
66 </section>
67
68 <section>
69 <title>Why Should We Use overlays.gentoo.org?</title>
70 <body>
71 <p>You don't have to. You don't have to have an overlay at all, and if you do
72 have one, you are absolutely free to host your own overlay somewhere else.
73 You don't have to host an overlay on o.g.o for it to be considered
74 "official".</p>
75
76 <p>The advantage of using overlays.gentoo.org is that we already have everything
77 setup for you. You don't need to admin your own server, or worry about
78 software upgrades. We take care of all of that for you.</p>
79 </body>
80 </section>
81
82 <section>
83 <title>When Should We Not Use overlays.gentoo.org?</title>
84 <body>
85 <p>The purpose of o.g.o is to help bridge the gap between developers and users.
86 Gentoo is a community-based distribution, and we believe that our users are
87 just as important a part of that community as developers are.</p>
88
89 <p>All of the overlays hosted on o.g.o are there for all users to download and
90 use. It's for users to make their own decision about what software they
91 install on their computers - and that includes choosing to use your overlay.
92 Some users will make bad decisions, and end up breaking their computer. They
93 may even end up blaming Gentoo as a result. That's okay; these people
94 probably go around blaming everyone but themselves for their own
95 mistakes anyway, and there's probably nothing you can do to change that.
96 But that still doesn't give any of us the right to choose for them.</p>
97
98 <p>Users are free (in fact, they are encouraged) to provide constructive
99 feedback about anything to do with Gentoo - including all of the overlays
100 hosted on o.g.o. That feedback can come via bugs.g.o, via email to your
101 project team or directly to you, via the forums, or via IRC. We're not
102 talking about genuinely abusive users; we have no time for those, and no-one
103 expects you to have any time for them either.</p>
104
105 <warn>If you're not happy with users using your overlay, and / or if you don't want
106 users bothering you about your overlay, then don't use o.g.o to host your
107 overlay.</warn>
108
109 <p>The other thing we need to say is that o.g.o is for hosting overlays. You
110 can't use it to be $UPSTREAM for your packages. If that's the kind of hosting
111 you need, you can use services such as <uri link="http://www.sourceforge.net/">SourceForge.net</uri>, <uri link="http://www.berlios.de">Berlios</uri>, or
112 Patrick's <uri link="http://www.gentooexperimental.org">GentooExperimental.org</uri>.</p>
113 </body>
114 </section>
115 </chapter>
116
117 <chapter>
118 <title>Requesting An Overlay</title>
119
120 <section>
121 <title>Introduction</title>
122 <body>
123 <p>There are two types of overlay - "project" overlays, and "developer"
124 overlays. The only difference between them is responsibility and
125 accountability.</p>
126
127 <impo>Before requesting an overlay, please make sure that you have read our <uri link="/proj/en/overlays/policy.xml">Policy Document</uri>. It clearly sets out what's allowed and what is not, and what your responsibilities will be.</impo>
128 </body>
129 </section>
130
131 <section>
132 <title>Project Overlays</title>
133 <body>
134 <p>"Project" overlays are overlays for official Gentoo projects. A good
135 example is <uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.</p>
136
137 <p>An official Gentoo project is a project that has a project page on
138 www.gentoo.org, and that has an elected lead. (This definition comes from <uri link="http://www.gentoo.org/proj/en/glep/glep-0039.html">the
139 metastructure document</uri>, which is Gentoo's governing document). The project
140 lead(s) are responsible for the project overlay, including its contents, and
141 any problems it causes other Gentoo projects and developers.</p>
142
143 <p>To request a project overlay, the project's lead just needs to pop into
144 #gentoo-overlays on IRC and ask for an overlay to be created. Or, if he/she
145 prefers, drop an email to overlays@gentoo.org. We'll take care of the rest,
146 including granting write access to all the members of your project (as listed
147 on your project page).</p>
148
149 <p>We will:</p>
150 <ul>
151 <li>create your overlay (trac site + svn)</li>
152 <li>add your overlay's RSS feed to the o.g.o homepage</li>
153 <li>create an o.g.o account for you if you don't already have one</li>
154 <li>give you write access to your overlay's Trac wiki and Subversion
155 repository</li>
156 <li>give write access to all project members who already have an o.g.o
157 account</li>
158 <li>contact all of the other project members, and sort out their access</li>
159 </ul>
160 </body>
161 </section>
162
163 <section>
164 <title>Developer Overlays</title>
165 <body>
166
167 <p>"Developer" overlays are overlays owned by individual Gentoo developers. One
168 example is <uri link="http://overlays.gentoo.org/dev/tcort">tcort's overlay</uri>.</p>
169
170 <p>If you have an @gentoo.org email address, and you've passed the ebuild quiz,
171 then you can have your own developer overlay on o.g.o.</p>
172
173 <p>To request a developer overlay, just pop into #gentoo-overlays on IRC and ask
174 for an overlay to be created for you. Or, if you prefer, drop an email to
175 overlays@gentoo.org.</p>
176
177 <p>We will:</p>
178 <ul>
179 <li>create your overlay (trac site + svn)</li>
180 <li>add your overlay's RSS feed to the o.g.o homepage</li>
181 <li>create an o.g.o account for you if you don't have one already</li>
182 <li>give you write access to your overlay's Trac wiki and Subversion
183 repository</li>
184 </ul>
185 </body>
186 </section>
187
188 <section>
189 <title>A Word About Accounts</title>
190 <body>
191 <p>Because o.g.o is designed to support a blend of both Gentoo developers and
192 Gentoo users, we don't create 'real' system-level accounts on the o.g.o host.
193 All access is currently through Apache, and is managed by Apache htpasswd and
194 htgroup files.</p>
195
196 <impo>You do *not* have SSH access to o.g.o.</impo>
197 </body>
198 </section>
199 </chapter>
200
201 <chapter>
202 <title>Working With Your Overlay</title>
203
204 <section>
205 <title>Introduction</title>
206 <body>
207 <p>You can access your overlay as soon as it has been created. Project and
208 developer overlays have different URLs, so that everyone can tell one from the
209 other, but otherwise they are identical in every way.</p>
210
211 <p>There are *no* read restrictions on overlays or wikis. Everyone has full
212 read access to all overlays and wikis. If you need a 'secret' overlay of some
213 kind, then o.g.o is not for you.</p>
214 </body>
215 </section>
216
217 <section>
218 <title>Accessing Project Overlays</title>
219 <body>
220 <p>If your project overlay is called 'foo', your Trac wiki site will be
221 here: http://overlays.gentoo.org/proj/foo/</p>
222
223 <p>To checkout your Subversion repository, use:</p>
224 <pre caption="Checkout your project overlay">svn co http://overlays.gentoo.org/svn/proj/foo/</pre>
225
226 <p>We maintain <uri link="http://overlays.gentoo.org/proj/">a full list of project overlays hosted on overlays.gentoo.org</uri>.</p>
227 </body>
228 </section>
229
230 <section>
231 <title>Accessing Developer Overlays</title>
232 <body>
233 <p>If your Gentoo email address is 'foo@gentoo.org', your Trac wiki site will be
234 here: http://overlays.gentoo.org/dev/foo/</p>
235
236 <p>To checkout your Subversion repository, use:</p>
237 <pre caption="Checkout your developer overlay">>svn co http://overlays.gentoo.org/svn/dev/foo/</pre>
238
239 <p>We maintain <uri link="http://overlays.gentoo.org/dev/">a full list of developer overlays hosted on overlays.gentoo.org</uri>.</p>
240 </body>
241 </section>
242
243 <section>
244 <title>Getting Started With Trac</title>
245 <body>
246 <p>Your overlay comes with <uri link="http://trac.edgewall.com">Trac</uri>. Trac is a wiki, a subversion repository browser, and a bug tracking system that's
247 very popular with open source developers.</p>
248
249 <p>We have disabled the bug tracking system in Trac. Use <uri link="http://bugs.gentoo.org">Gentoo's bugzilla</uri> for bug tracking your overlay.</p>
250
251 <p>Your overlay's RSS feed - the one that is shown on <uri link="http://overlays.gentoo.org">the o.g.o homepage</uri> - comes from Trac's Timeline page.</p>
252
253 <p>We have installed several Trac plugins, which we hope will make your wiki even
254 more useful to you. If you come across any additional plugins that you'd like
255 to see installed, please let us know, and we'll take a look at them.</p>
256
257 <impo>more here, including details about each Trac plugin that we have installed</impo>
258 </body>
259 </section>
260
261 <section>
262 <title>Getting Started With Subversion</title>
263 <body>
264 <p>Your overlay comes with <uri link="http://subversion.tigris.org">Subversion</uri>, a modern alternative to CVS. The advantages of Subversion over CVS include real versioning of directories, full changeset support, and it's much easier to do branching if you need to. The main disadvantage of Subversion is that it is slower than CVS, and that a local Subversion checkout requires more disk space.</p>
265
266 <p>If you have never used Subversion before, the <uri link="http://svnbook.red-bean.com/">online book</uri> is an excellent online book for Subversion. You can buy it in dead-tree format too if you
267 prefer.</p>
268
269 <impo>more here, including basic checkout, status, commit and update commands</impo>
270
271 </body>
272 </section>
273
274 <section>
275 <title>Layman</title>
276 <body>
277 <p>We are telling users to use layman to download and manage your overlay.
278 layman is a utility written by <mail link="wrobel@gentoo.org">Gunnar Wrobel</mail> which makes it very easy for users to work with overlays.</p>
279
280 <p>To get started with using layman, see <uri link="http://www.gentoo.org/news/en/gwn/20060522-newsletter.xml">Gentoo Weekly News for 22nd May</uri>, <uri link="http://gentoo-wiki.com/TIP_Overlays#layman">this article on Gentoo-Wiki.com</uri>, or the man page that comes with layman.</p>
281 </body>
282 </section>
283
284 <section>
285 <title>Auto-Sync From Portage</title>
286 <body>
287 <p>Your packages in the Portage tree are always at risk of being changed without
288 you knowing about it in advance. Arch teams need to be able to keyword
289 packages (and fix arch-specific brokenness), the QA team fix perceived
290 standards violations, and occaisionally developers will edit packages that
291 they shouldn't.</p>
292
293 <p>You need to make sure that the changes made in Portage aren't lost the next
294 time you copy your packages from your overlay back into Portage.</p>
295
296 <p>The PHP team have solved this problem by automatically copying their packages
297 from Portage back into a 'portage' branch of their overlay every night. They
298 can then use Subversion (or Trac's timeline) to see what has changed every
299 day.</p>
300
301 <p>If you'd like to have this feature added to your overlay, contact CHTEKK.</p>
302 </body>
303 </section>
304 </chapter>
305
306 <chapter>
307 <title>Giving Access To Your Overlay To Others</title>
308
309 <section>
310 <title>Introduction</title>
311 <body>
312 <p>One of the key features of o.g.o is that people who do not have write access
313 to the Gentoo Portage package tree can have write access to one or more
314 overlays. Several Gentoo projects have found that this is a great way to train
315 and evaluate potential Gentoo developers in a safe environment.</p>
316
317 <p>At the moment, only the Overlays team can update the access control lists for
318 overlays.gentoo.org. We will provide a web-based tool for managing the access
319 control lists at a later date. But, for now, if you need a change made,
320 please drop by #gentoo-overlays on IRC for assistance.</p>
321 </body>
322 </section>
323
324 <section>
325 <title>Project Overlays: Giving Write Access To Team Members</title>
326 <body>
327 <p>Any developer listed on a team's project page on www.g.o can have write
328 access to the team's overlay. The project lead can ask on their behalf, or
329 the developer can come and ask for access themselves.</p>
330
331 <p>If the developer doesn't have an o.g.o account yet, he/she will need to drop
332 by #gentoo-overlays so that we can create an account for them.</p>
333 </body>
334 </section>
335
336 <section>
337 <title>Project Overlays: Giving Write Access To Other Gentoo
338 Developers</title>
339 <body>
340
341 <p>Any Gentoo developer *not* listed on a team's project page on www.g.o can
342 have write access to the team's overlay. The request for write access must
343 come from a member of the team. It doesn't have to come from the project
344 lead.</p>
345
346 <p>If the developer doesn't have an o.g.o account yet, he/she will need to drop
347 by #gentoo-overlays so that we can create an account for them.</p>
348 </body>
349 </section>
350
351 <section>
352 <title>Project Overlays: Giving Write Access To Gentoo Users</title>
353 <body>
354 <p>Any Gentoo user can have write access to the team's overlay. The request for
355 write access must come from one of the project's leads. You can request that
356 we give the user write access to Trac, to Subversion, or to both. (We will
357 assume that the request is for write access to both, unless you say
358 otherwise).</p>
359
360 <p>We cannot accept these requests from anyone other than a project lead. If
361 your project only has the one lead, we recommend electing a second lead. If
362 your one and only lead is AWOL, consider electing a replacement :)</p>
363
364 <p>If the user doesn't have an o.g.o account yet, he/she will need to drop by
365 #gentoo-overlays so that we can create an account for them.</p>
366 </body>
367 </section>
368
369 <section>
370 <title>Developer Overlays: Giving Write Access To Gentoo Developers</title>
371 <body>
372 <p>Any Gentoo developer can have write access to your developer overlay. The
373 developer can ask us directly; we will not give access until we've checked
374 with you. You can also ask us to give write access to any named
375 developer.</p>
376
377 <p>If the developer doesn't have an o.g.o account yet, he/she will need to drop
378 by #gentoo-overlays so that we can create an account for them.</p>
379 </body>
380 </section>
381
382 <section>
383 <title>Developer Overlays: Giving Write Access To Gentoo Users</title>
384 <body>
385 <p>Any Gentoo user can have write access to your developer's overlay. The
386 request for write access must come from you. You can request that we give
387 the user write access just to Trac, just to Subversion, or to both. (We will
388 assume that the request is for write access to both unless you say
389 otherwise).</p>
390
391 <p>We cannot accept these requests from anyone else other than you. If you find
392 yourself giving access to a lot of other people, it might be that you should
393 consider setting up a new project, and transfering your work there
394 instead.</p>
395
396 <p>If the user doesn't have an o.g.o account yet, he/she will need to drop by
397 #gentoo-overlays so that we can create an account for them.</p>
398 </body>
399 </section>
400 </chapter>
401
402 <chapter>
403 <title>Accessing Someone Else's Overlay</title>
404
405 <section>
406 <title>Using An Overlay</title>
407 <body>
408 <p>Everyone has full read access to every overlay. We recommend that you
409 use</p>
410 <pre caption="Install layman">
411 emerge layman
412 echo 'source /usr/portage/local/layman/layman.conf' &gt;&gt; /etc/make.conf
413 </pre>
414
415 <p>After that, to view the list of overlays, use</p>
416
417 <pre caption="List overlays that layman knows about">layman -L</pre>
418
419 <p>To install an overlay, use</p>
420 <pre caption="Install an overlay">layman -a &lt;overlay-name&gt;</pre>
421
422 <p>You can now install packages from the overlay.</p>
423 </body>
424 </section>
425
426 <section>
427 <title>Requesting Write Access</title>
428 <body>
429 <p>If you want write access to a project overlay, contact a member of the
430 project team, and ask them for access. If they approve your request, they
431 will arrange for you to have write access, by contacting the Overlays
432 team.</p>
433
434 <p>If you want write access to a developer's overlay, contact the developer
435 directly, and ask them for access. If they approve your request, they will
436 arrange for you to have write access, by contacting the Overlays team.</p>
437 </body>
438 </section>
439 </chapter>
440
441 <chapter>
442 <title>Frequently Asked Questions</title>
443
444 <section>
445 <title>o.g.o Administration</title>
446 <body>
447
448 <p>Q: How do I contact the o.g.o admin staff?</p>
449 <ul>
450 <li>A: You can pop into #gentoo-overlays on IRC, and talk to us there. The
451 current staff are mostly in European timezones.</li>
452 <li>A: You can send an email to overlays@gentoo.org. Someone will answer you as
453 soon as possible.</li>
454 <li>A: You can contact Stuart Herbert (the project leader) directly, via his
455 email address: stuart@gentoo.org.</li>
456 </ul>
457
458 <p>Q: Why can't I edit the access control list directly?</p>
459 <ul>
460 <li>A: The access control list currently lives in htpasswd / htgroup files used
461 by Apache. Only o.g.o admin staff have ssh access into the o.g.o box.</li>
462 </ul>
463 </body>
464 </section>
465
466 <section>
467 <title>Security</title>
468 <body>
469 <p>Q: Is my overlay available via https?</p>
470 <ul>
471 <li>A: No, it currently is not. We have asked infra to set this up, and are
472 waiting for them to do so.</li>
473 </ul>
474 </body>
475 </section>
476
477 <section>
478 <title>Multiple Overlays</title>
479 <body>
480
481 <p>Q: Can I have multiple overlays?</p>
482 <ul>
483 <li>A: Yes, in a fashion. Inside your overlay, you can create
484 sub-directories, and put separate package trees inside those sub-directories.
485 Please take a look at the PHP project overlay for an example.</li>
486 </ul>
487 </body>
488 </section>
489
490 <section>
491 <title>Importing Existing Overlays</title>
492 <body>
493 <p>Q: I already have an overlay, and I'd like to move it to o.g.o. How do I
494 go about doing that?</p>
495 <ul>
496 <li>A: Create a tarball of your subversion repository, and put it somewhere
497 where it can be downloaded via http. We'll download it and install it onto
498 o.g.o for you.</li>
499 </ul>
500 <note>Make sure you tar up your repository, and not a checkout!</note>
501
502 <p>Q: I have an overlay, but it doesn't use Subversion. How do I go about
503 moving it to o.g.o?</p>
504 <ul>
505 <li>A: Ask us to create a new, empty overlay for you. You can then use 'svn
506 import' to import your files into the new overlay. You'll lose your history,
507 but that can't be helped.</li>
508 <li>A: Search the Internet, and see if there is a tool to convert from your
509 existing version control software to Subversion. If there is, use that, and
510 then we can help you move it to o.g.o.</li>
511 <li>A: If your version control software is used by Trac, and it can be used
512 over HTTP, come and help us add
513 support for your version control software on o.g.o.</li>
514 </ul>
515 </body>
516 </section>
517
518 <section>
519 <title>"Official" Overlays</title>
520 <body>
521 <p>Q: When is an overlay considered "official"?</p>
522 <ul>
523 <li>A: An "official" overlay is an overlay managed by a Gentoo project (for
524 project overlays) or a Gentoo developer (for developer overlays).</li>
525 </ul>
526
527 <p>Q: Does an overlay have to be on o.g.o to be "official"?</p>
528 <ul>
529 <li>A: No.</li>
530 </ul>
531 </body>
532 </section>
533 </chapter>
534 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20