/[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.13 - (hide annotations) (download) (as text)
Sun Oct 12 09:55:49 2008 UTC (9 years, 9 months ago) by robbat2
Branch: MAIN
Changes since 1.12: +7 -4 lines
File MIME type: application/xml
We do allow $UPSTREAM now.

1 stuart 1.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 robbat2 1.11 <mail link="stuart">Stuart Herbert</mail>
9     </author>
10     <author title="Author">
11     <mail link="jokey">Markus Ullmann</mail>
12     </author>
13     <author title="Author">
14     <mail link="robbat2">Robin H. Johnson</mail>
15 stuart 1.1 </author>
16    
17     <abstract>This guide helps developers understand how to use the Gentoo
18     Overlays service.</abstract>
19    
20     <license/>
21    
22 robbat2 1.11 <version>2.0</version>
23     <date>2008-10-12</date>
24 stuart 1.1
25     <chapter>
26     <title>Introduction</title>
27    
28     <section>
29     <title>Audience</title>
30     <body>
31     <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>
32     </body>
33     </section>
34    
35     <section>
36     <title>What is overlays.gentoo.org?</title>
37     <body>
38     <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>
39     </body>
40     </section>
41    
42     <section>
43     <title>Who Can Use overlays.gentoo.org?</title>
44     <body>
45     <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>
46    
47     <p>Any Gentoo staff member or user (ie, anyone who doesn't have write access to
48     the main Portage package tree) can download and use the contents of any hosted
49     overlay. If you choose, you can also give users write access to your
50     overlay.</p>
51     </body>
52     </section>
53    
54     <section>
55     <title>What Does overlays.gentoo.org Give Me?</title>
56     <body>
57     <p>The overlays.gentoo.org service currently provides:</p>
58     <ul>
59     <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>
60 robbat2 1.11 <li><uri link="http://subversion.tigris.org">Subversion</uri> - a centralised version control system</li>
61 stuart 1.1 <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>
62 robbat2 1.11 <li><uri link="http://git.or.cz">Git</uri> - Fast Version Control System</li>
63 robbat2 1.12 <li><uri link="http://git.or.cz/gitwiki/Gitweb">gitweb</uri> - provides full-fledged web interface for viewing Git repositories.</li>
64 stuart 1.1 </ul>
65    
66     <p>... all hosted on secure, backed-up Gentoo infrastructure, administered by
67     <uri link="/proj/en/infrastructure">the Gentoo Infrastructure team</uri> (hardware / base OS) and <uri link="/proj/en/overlays">the Gentoo Overlays team</uri>
68     (wiki / VCS / ACLs).</p>
69    
70 robbat2 1.11 <p>Each overlay has separate authentication lists for Trac, Subversion and Git.
71 stuart 1.1 It's no problem at all to give someone write access to just Trac (e.g. for
72     writing documentation) without giving them write access to Subversion.</p>
73     </body>
74     </section>
75    
76     <section>
77     <title>Why Should We Use overlays.gentoo.org?</title>
78     <body>
79     <p>You don't have to. You don't have to have an overlay at all, and if you do
80     have one, you are absolutely free to host your own overlay somewhere else.
81     You don't have to host an overlay on o.g.o for it to be considered
82     "official".</p>
83    
84     <p>The advantage of using overlays.gentoo.org is that we already have everything
85     setup for you. You don't need to admin your own server, or worry about
86     software upgrades. We take care of all of that for you.</p>
87     </body>
88     </section>
89    
90     <section>
91     <title>When Should We Not Use overlays.gentoo.org?</title>
92     <body>
93     <p>The purpose of o.g.o is to help bridge the gap between developers and users.
94     Gentoo is a community-based distribution, and we believe that our users are
95     just as important a part of that community as developers are.</p>
96    
97     <p>All of the overlays hosted on o.g.o are there for all users to download and
98     use. It's for users to make their own decision about what software they
99     install on their computers - and that includes choosing to use your overlay.
100     Some users will make bad decisions, and end up breaking their computer. They
101     may even end up blaming Gentoo as a result. That's okay; these people
102     probably go around blaming everyone but themselves for their own
103     mistakes anyway, and there's probably nothing you can do to change that.
104     But that still doesn't give any of us the right to choose for them.</p>
105    
106     <p>Users are free (in fact, they are encouraged) to provide constructive
107     feedback about anything to do with Gentoo - including all of the overlays
108     hosted on o.g.o. That feedback can come via bugs.g.o, via email to your
109     project team or directly to you, via the forums, or via IRC. We're not
110     talking about genuinely abusive users; we have no time for those, and no-one
111     expects you to have any time for them either.</p>
112    
113     <warn>If you're not happy with users using your overlay, and / or if you don't want
114     users bothering you about your overlay, then don't use o.g.o to host your
115     overlay.</warn>
116    
117 robbat2 1.13 <p>o.g.o used to have restrictions of not being the $UPSTREAM for packages.
118     This restriction has been adjusted. We do offer hosting as the $UPSTREAM now,
119     but only for packages that are Gentoo-specific or important to the running of
120     Gentoo. Other hosting may be more suitable, some services in this vein are:
121     <uri link="http://www.sourceforge.net/">SourceForge.net</uri>, <uri
122     link="http://www.berlios.de">Berlios</uri>, or Patrick's <uri
123     link="http://www.gentooexperimental.org">GentooExperimental.org</uri>.</p>
124 stuart 1.1 </body>
125     </section>
126     </chapter>
127    
128     <chapter>
129     <title>Requesting An Overlay</title>
130    
131     <section>
132     <title>Introduction</title>
133     <body>
134     <p>There are two types of overlay - "project" overlays, and "developer"
135     overlays. The only difference between them is responsibility and
136     accountability.</p>
137    
138     <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>
139     </body>
140     </section>
141    
142     <section>
143     <title>Project Overlays</title>
144     <body>
145     <p>"Project" overlays are overlays for official Gentoo projects. A good
146     example is <uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.</p>
147    
148     <p>An official Gentoo project is a project that has a project page on
149     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
150     metastructure document</uri>, which is Gentoo's governing document). The project
151     lead(s) are responsible for the project overlay, including its contents, and
152     any problems it causes other Gentoo projects and developers.</p>
153    
154 robbat2 1.11 <p>To request a SVN project overlay, the project's lead just needs to pop into
155 stuart 1.1 #gentoo-overlays on IRC and ask for an overlay to be created. Or, if he/she
156     prefers, drop an email to overlays@gentoo.org. We'll take care of the rest,
157     including granting write access to all the members of your project (as listed
158     on your project page).</p>
159    
160 robbat2 1.11 <p>To request a Git project overlay, just visit the <uri
161     link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
162     setup instructions, emailing the completed template as directed.</p>
163    
164     <p>For an SVN request, we will:</p>
165 stuart 1.1 <ul>
166     <li>create your overlay (trac site + svn)</li>
167     <li>add your overlay's RSS feed to the o.g.o homepage</li>
168     <li>create an o.g.o account for you if you don't already have one</li>
169     <li>give you write access to your overlay's Trac wiki and Subversion
170     repository</li>
171     <li>give write access to all project members who already have an o.g.o
172     account</li>
173     <li>contact all of the other project members, and sort out their access</li>
174     </ul>
175 robbat2 1.11
176     <p>For an Git request, we will:</p>
177     <ul>
178 robbat2 1.12 <li>create your overlay (git, gitweb, no trac)</li>
179 robbat2 1.11 <li>add your overlay's RSS feed to the o.g.o homepage</li>
180     <li>create an git.o.g.o account for you if you don't already have one</li>
181     <li>give you write access to your overlays Git repository</li>
182     <li>give write access to all project members who already have an o.g.o account</li>
183     <li>contact all of the other project members, and sort out their access</li>
184     </ul>
185    
186    
187 stuart 1.1 </body>
188     </section>
189    
190     <section>
191     <title>Developer Overlays</title>
192     <body>
193    
194     <p>"Developer" overlays are overlays owned by individual Gentoo developers. One
195     example is <uri link="http://overlays.gentoo.org/dev/tcort">tcort's overlay</uri>.</p>
196    
197     <p>If you have an @gentoo.org email address, and you've passed the ebuild quiz,
198     then you can have your own developer overlay on o.g.o.</p>
199    
200 robbat2 1.11 <p>To request a SVN developer overlay, just pop into #gentoo-overlays on IRC
201     and ask for an overlay to be created for you. Or, if you prefer, drop an email
202     to overlays@gentoo.org.</p>
203    
204     <p>To request a Git developer overlay, just visit the <uri
205     link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
206     setup instructions, emailing the completed template as directed.</p>
207 stuart 1.1
208 robbat2 1.11 <p>For an SVN request, we will:</p>
209 stuart 1.1 <ul>
210     <li>create your overlay (trac site + svn)</li>
211     <li>add your overlay's RSS feed to the o.g.o homepage</li>
212     <li>create an o.g.o account for you if you don't have one already</li>
213     <li>give you write access to your overlay's Trac wiki and Subversion
214     repository</li>
215     </ul>
216 robbat2 1.11
217     <p>For an Git request, we will:</p>
218     <ul>
219 robbat2 1.12 <li>create your overlay (git, gitweb, no trac)</li>
220 robbat2 1.11 <li>add your overlay's RSS feed to the o.g.o homepage</li>
221     <li>create an git.o.g.o account for you if you don't already have one</li>
222     <li>give you write access to your overlays Git repository</li>
223     </ul>
224 stuart 1.1 </body>
225     </section>
226    
227     <section>
228     <title>A Word About Accounts</title>
229     <body>
230     <p>Because o.g.o is designed to support a blend of both Gentoo developers and
231     Gentoo users, we don't create 'real' system-level accounts on the o.g.o host.
232     All access is currently through Apache, and is managed by Apache htpasswd and
233     htgroup files.</p>
234    
235     <impo>You do *not* have SSH access to o.g.o.</impo>
236     </body>
237     </section>
238     </chapter>
239    
240     <chapter>
241     <title>Working With Your Overlay</title>
242    
243     <section>
244     <title>Introduction</title>
245     <body>
246     <p>You can access your overlay as soon as it has been created. Project and
247     developer overlays have different URLs, so that everyone can tell one from the
248     other, but otherwise they are identical in every way.</p>
249    
250     <p>There are *no* read restrictions on overlays or wikis. Everyone has full
251     read access to all overlays and wikis. If you need a 'secret' overlay of some
252     kind, then o.g.o is not for you.</p>
253     </body>
254     </section>
255    
256     <section>
257     <title>Accessing Project Overlays</title>
258     <body>
259     <p>If your project overlay is called 'foo', your Trac wiki site will be
260     here: http://overlays.gentoo.org/proj/foo/</p>
261    
262     <p>To checkout your Subversion repository, use:</p>
263 robbat2 1.10 <pre caption="Checkout your project overlay">svn co https://overlays.gentoo.org/svn/proj/foo/</pre>
264    
265     <p>While you may perform read-only actions via unsecure HTTP, you must perform
266     all commits via HTTPS. If you need to switch between modes, use:</p>
267     <pre caption="Switching your project overlay from HTTP to HTTPS">svn sw --relocate http://overlays.gentoo.org/svn/proj/foo/ https://overlays.gentoo.org/svn/proj/foo/</pre>
268 stuart 1.1
269     <p>We maintain <uri link="http://overlays.gentoo.org/proj/">a full list of project overlays hosted on overlays.gentoo.org</uri>.</p>
270     </body>
271     </section>
272    
273     <section>
274     <title>Accessing Developer Overlays</title>
275     <body>
276     <p>If your Gentoo email address is 'foo@gentoo.org', your Trac wiki site will be
277     here: http://overlays.gentoo.org/dev/foo/</p>
278    
279     <p>To checkout your Subversion repository, use:</p>
280 robbat2 1.10 <pre caption="Checkout your developer overlay">svn co https://overlays.gentoo.org/svn/dev/foo/</pre>
281    
282     <p>While you may perform read-only actions via unsecure HTTP, you must perform
283     all commits via HTTPS. If you need to switch between modes, use:</p>
284     <pre caption="Switching your developer overlay from HTTP to HTTPS">svn sw --relocate http://overlays.gentoo.org/svn/dev/foo/ https://overlays.gentoo.org/svn/dev/foo/</pre>
285 stuart 1.1
286     <p>We maintain <uri link="http://overlays.gentoo.org/dev/">a full list of developer overlays hosted on overlays.gentoo.org</uri>.</p>
287     </body>
288     </section>
289    
290     <section>
291     <title>Getting Started With Trac</title>
292     <body>
293     <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
294     very popular with open source developers.</p>
295    
296     <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>
297    
298     <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>
299    
300     <p>We have installed several Trac plugins, which we hope will make your wiki even
301     more useful to you. If you come across any additional plugins that you'd like
302     to see installed, please let us know, and we'll take a look at them.</p>
303    
304 stuart 1.2 <ul>
305     <li><e>LayOnTrac</e> - lists the packages from the overlay.</li>
306     <li><uri link="http://muness.textdriven.com/trac/wiki/tags/Setup">TracTags</uri> - displays a tag cloud</li>
307     <li><uri link="http://trac.edgewall.org/wiki/WebAdmin">TracWebAdmin</uri> - provides web-based admin panel for Trac</li>
308     </ul>
309    
310     <p>We have installed several Trac macros, which we hope will make your wiki even more useful to you. If you come across any additional macros that you'd like to see installed, please let us know, and we'll take a look at them.</p>
311    
312     <ul>
313     <li><uri link="http://trac-hacks.org/wiki/AddCommentMacro">AddComment</uri> - allows visitors to add comments to the bottom of your pages</li>
314     <li><uri link="http://trac-hacks.org/wiki/FootNoteMacro">FootNote</uri> - adds support for adding footnotes to a page</li>
315     <li><uri link="http://trac-hacks.org/wiki/TocMacro">TOC</uri> - adds support for publishing a Table of Contents on a page</li>
316     </ul>
317    
318 stuart 1.1 </body>
319     </section>
320    
321     <section>
322     <title>Getting Started With Subversion</title>
323     <body>
324     <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>
325    
326 stuart 1.3 <p>If you have never used Subversion before, the <uri link="http://svnbook.red-bean.com/">online book</uri> is an excellent way to learn Subversion. You can buy it in dead-tree format too if you prefer.</p>
327 stuart 1.1
328 stuart 1.2 <p>Here are some basic commands to get you started.</p>
329 robbat2 1.10 <pre caption="Checking out your overlay">svn co https://overlays.gentoo.org/proj/php</pre>
330 stuart 1.2 <pre caption="Seeing which files need committing">svn status</pre>
331     <pre caption="Adding files to your overlay">svn add my.ebuild</pre>
332     <pre caption="Committing your changes">svn commit -m 'My changelog entry'</pre>
333 stuart 1.1
334     </body>
335     </section>
336    
337     <section>
338     <title>Layman</title>
339     <body>
340     <p>We are telling users to use layman to download and manage your overlay.
341     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>
342    
343     <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>
344     </body>
345     </section>
346    
347     <section>
348     <title>Auto-Sync From Portage</title>
349     <body>
350     <p>Your packages in the Portage tree are always at risk of being changed without
351     you knowing about it in advance. Arch teams need to be able to keyword
352     packages (and fix arch-specific brokenness), the QA team fix perceived
353     standards violations, and occaisionally developers will edit packages that
354     they shouldn't.</p>
355    
356     <p>You need to make sure that the changes made in Portage aren't lost the next
357     time you copy your packages from your overlay back into Portage.</p>
358    
359     <p>The PHP team have solved this problem by automatically copying their packages
360     from Portage back into a 'portage' branch of their overlay every night. They
361 chtekk 1.9 can then use Subversion (or Trac's timeline) to see what has changed every day.</p>
362 stuart 1.1
363     </body>
364     </section>
365     </chapter>
366    
367     <chapter>
368 genstef 1.8 <title>Using git on overlays</title>
369    
370     <section>
371     <title>Initializing your overlay</title>
372     <body>
373     <p>Before uploading you need to locally create a git repository and add all items:</p>
374     <pre caption="go to your overlay">cd ~/my-overlay</pre>
375     <pre caption="create a new git repo">git init
376     git add .
377     git commit -m "populate overlay"</pre>
378 robbat2 1.11 <p>Note that this commit was only locally, now we get the server into the game.</p>
379     <pre caption="tell git the url">git remote add origin git+ssh://git@git.overlays.gentoo.org/(proj or dev)/(name)</pre>
380     <pre caption="finally get it up there">git push origin master</pre>
381 genstef 1.8 <p>Source: http://www.kernel.org/pub/software/scm/git/docs/tutorial.html</p>
382     </body></section>
383    
384     <section>
385     <title>Checking out the overlay with git</title>
386     <body>
387 robbat2 1.11 <pre caption="clone it!">git clone git://git@git.overlays.gentoo.org/(proj or dev)/(name)/</pre>
388 genstef 1.8 </body>
389     </section>
390     </chapter>
391    
392     <chapter>
393 stuart 1.1 <title>Giving Access To Your Overlay To Others</title>
394    
395     <section>
396     <title>Introduction</title>
397     <body>
398     <p>One of the key features of o.g.o is that people who do not have write access
399     to the Gentoo Portage package tree can have write access to one or more
400     overlays. Several Gentoo projects have found that this is a great way to train
401     and evaluate potential Gentoo developers in a safe environment.</p>
402    
403     <p>At the moment, only the Overlays team can update the access control lists for
404     overlays.gentoo.org. We will provide a web-based tool for managing the access
405     control lists at a later date. But, for now, if you need a change made,
406     please drop by #gentoo-overlays on IRC for assistance.</p>
407     </body>
408     </section>
409    
410     <section>
411     <title>Project Overlays: Giving Write Access To Team Members</title>
412     <body>
413     <p>Any developer listed on a team's project page on www.g.o can have write
414     access to the team's overlay. The project lead can ask on their behalf, or
415     the developer can come and ask for access themselves.</p>
416    
417     <p>If the developer doesn't have an o.g.o account yet, he/she will need to drop
418     by #gentoo-overlays so that we can create an account for them.</p>
419     </body>
420     </section>
421    
422     <section>
423     <title>Project Overlays: Giving Write Access To Other Gentoo
424     Developers</title>
425     <body>
426    
427     <p>Any Gentoo developer *not* listed on a team's project page on www.g.o can
428     have write access to the team's overlay. The request for write access must
429     come from a member of the team. It doesn't have to come from the project
430     lead.</p>
431    
432     <p>If the developer doesn't have an o.g.o account yet, he/she will need to drop
433     by #gentoo-overlays so that we can create an account for them.</p>
434     </body>
435     </section>
436    
437     <section>
438     <title>Project Overlays: Giving Write Access To Gentoo Users</title>
439     <body>
440     <p>Any Gentoo user can have write access to the team's overlay. The request for
441     write access must come from one of the project's leads. You can request that
442     we give the user write access to Trac, to Subversion, or to both. (We will
443     assume that the request is for write access to both, unless you say
444     otherwise).</p>
445    
446     <p>We cannot accept these requests from anyone other than a project lead. If
447     your project only has the one lead, we recommend electing a second lead. If
448     your one and only lead is AWOL, consider electing a replacement :)</p>
449    
450     <p>If the user doesn't have an o.g.o account yet, he/she will need to drop by
451     #gentoo-overlays so that we can create an account for them.</p>
452     </body>
453     </section>
454    
455     <section>
456     <title>Developer Overlays: Giving Write Access To Gentoo Developers</title>
457     <body>
458     <p>Any Gentoo developer can have write access to your developer overlay. The
459     developer can ask us directly; we will not give access until we've checked
460     with you. You can also ask us to give write access to any named
461     developer.</p>
462    
463     <p>If the developer doesn't have an o.g.o account yet, he/she will need to drop
464     by #gentoo-overlays so that we can create an account for them.</p>
465     </body>
466     </section>
467    
468     <section>
469     <title>Developer Overlays: Giving Write Access To Gentoo Users</title>
470     <body>
471     <p>Any Gentoo user can have write access to your developer's overlay. The
472     request for write access must come from you. You can request that we give
473     the user write access just to Trac, just to Subversion, or to both. (We will
474     assume that the request is for write access to both unless you say
475     otherwise).</p>
476    
477     <p>We cannot accept these requests from anyone else other than you. If you find
478     yourself giving access to a lot of other people, it might be that you should
479     consider setting up a new project, and transfering your work there
480     instead.</p>
481    
482     <p>If the user doesn't have an o.g.o account yet, he/she will need to drop by
483     #gentoo-overlays so that we can create an account for them.</p>
484     </body>
485     </section>
486     </chapter>
487    
488     <chapter>
489     <title>Accessing Someone Else's Overlay</title>
490    
491     <section>
492     <title>Using An Overlay</title>
493     <body>
494     <p>Everyone has full read access to every overlay. We recommend that you
495     use</p>
496     <pre caption="Install layman">
497     emerge layman
498     echo 'source /usr/portage/local/layman/layman.conf' &gt;&gt; /etc/make.conf
499     </pre>
500    
501 wrobel 1.6 <note>
502 wrobel 1.7 Layman will create "/usr/portage/local/layman/make.conf" once you add
503     your first overlay. But if you do not plan to install an overlay
504     immediately you should ensure that this file actually exists and
505     contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will
506     complain. You can run "echo PORTDIR_OVERLAY=\"\" >
507     /usr/portage/local/layman/make.conf" in order to have the file created
508     correctly.
509 wrobel 1.6 </note>
510    
511 stuart 1.1 <p>After that, to view the list of overlays, use</p>
512    
513     <pre caption="List overlays that layman knows about">layman -L</pre>
514    
515     <p>To install an overlay, use</p>
516     <pre caption="Install an overlay">layman -a &lt;overlay-name&gt;</pre>
517    
518     <p>You can now install packages from the overlay.</p>
519     </body>
520     </section>
521    
522     <section>
523     <title>Requesting Write Access</title>
524     <body>
525     <p>If you want write access to a project overlay, contact a member of the
526     project team, and ask them for access. If they approve your request, they
527     will arrange for you to have write access, by contacting the Overlays
528     team.</p>
529    
530     <p>If you want write access to a developer's overlay, contact the developer
531     directly, and ask them for access. If they approve your request, they will
532     arrange for you to have write access, by contacting the Overlays team.</p>
533     </body>
534     </section>
535     </chapter>
536    
537     <chapter>
538     <title>Frequently Asked Questions</title>
539    
540     <section>
541     <title>o.g.o Administration</title>
542     <body>
543    
544     <p>Q: How do I contact the o.g.o admin staff?</p>
545     <ul>
546     <li>A: You can pop into #gentoo-overlays on IRC, and talk to us there. The
547     current staff are mostly in European timezones.</li>
548     <li>A: You can send an email to overlays@gentoo.org. Someone will answer you as
549     soon as possible.</li>
550     </ul>
551    
552     <p>Q: Why can't I edit the access control list directly?</p>
553     <ul>
554 robbat2 1.11 <li>A: (SVN) The access control list currently lives in htpasswd / htgroup files used
555 stuart 1.1 by Apache. Only o.g.o admin staff have ssh access into the o.g.o box.</li>
556 robbat2 1.11 <li>A: (Git) The access control list currently lives in the gitosis-admin repository,
557     which is writable only by the o.g.o staff.</li>
558 stuart 1.1 </ul>
559     </body>
560     </section>
561    
562     <section>
563     <title>Security</title>
564     <body>
565     <p>Q: Is my overlay available via https?</p>
566     <ul>
567 stuart 1.4 <li>A: Yes, it is.</li>
568 stuart 1.1 </ul>
569     </body>
570     </section>
571    
572     <section>
573     <title>Multiple Overlays</title>
574     <body>
575    
576     <p>Q: Can I have multiple overlays?</p>
577     <ul>
578     <li>A: Yes, in a fashion. Inside your overlay, you can create
579     sub-directories, and put separate package trees inside those sub-directories.
580     Please take a look at the PHP project overlay for an example.</li>
581     </ul>
582     </body>
583     </section>
584    
585     <section>
586     <title>Importing Existing Overlays</title>
587     <body>
588     <p>Q: I already have an overlay, and I'd like to move it to o.g.o. How do I
589     go about doing that?</p>
590     <ul>
591     <li>A: Create a tarball of your subversion repository, and put it somewhere
592     where it can be downloaded via http. We'll download it and install it onto
593     o.g.o for you.</li>
594     </ul>
595     <note>Make sure you tar up your repository, and not a checkout!</note>
596    
597     <p>Q: I have an overlay, but it doesn't use Subversion. How do I go about
598     moving it to o.g.o?</p>
599     <ul>
600     <li>A: Ask us to create a new, empty overlay for you. You can then use 'svn
601     import' to import your files into the new overlay. You'll lose your history,
602     but that can't be helped.</li>
603     <li>A: Search the Internet, and see if there is a tool to convert from your
604     existing version control software to Subversion. If there is, use that, and
605     then we can help you move it to o.g.o.</li>
606     <li>A: If your version control software is used by Trac, and it can be used
607     over HTTP, come and help us add
608     support for your version control software on o.g.o.</li>
609     </ul>
610     </body>
611     </section>
612    
613     <section>
614     <title>"Official" Overlays</title>
615     <body>
616     <p>Q: When is an overlay considered "official"?</p>
617     <ul>
618     <li>A: An "official" overlay is an overlay managed by a Gentoo project (for
619     project overlays) or a Gentoo developer (for developer overlays).</li>
620     </ul>
621    
622     <p>Q: Does an overlay have to be on o.g.o to be "official"?</p>
623     <ul>
624     <li>A: No.</li>
625     </ul>
626     </body>
627     </section>
628     </chapter>
629     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20