/[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.24 - (hide annotations) (download) (as text)
Sun Feb 1 14:15:50 2015 UTC (3 years, 9 months ago) by mgorny
Branch: MAIN
CVS Tags: HEAD
Changes since 1.23: +1 -1 lines
File MIME type: application/xml
Project migrated to wiki.

1 stuart 1.1 <?xml version="1.0" encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3    
4 mgorny 1.24 <guide disclaimer="obsolete" redirect="https://wiki.gentoo.org/wiki/Project:Overlays/Dev_Guide">
5 stuart 1.1 <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 tampakrap 1.19 <author title="Author">
17     <mail link="tampakrap">Theo Chatzimichos</mail>
18     </author>
19 stuart 1.1
20 tampakrap 1.19
21     <abstract>
22     This guide helps developers and contributors understand how to
23     use the Gentoo Overlays service.
24     </abstract>
25 stuart 1.1
26     <license/>
27    
28 tampakrap 1.19 <version>2.4</version>
29     <date>2010-05-01</date>
30 stuart 1.1
31     <chapter>
32     <title>Introduction</title>
33    
34     <section>
35     <title>Audience</title>
36     <body>
37 tampakrap 1.19
38     <p>
39     This document has been written for Gentoo developers and users that want to
40     contribute. If you just want to start downloading and using overlays, please
41     see the <uri link="/proj/en/overlays/userguide.xml">Gentoo Overlays User Guide</uri>
42     instead.
43     </p>
44    
45 stuart 1.1 </body>
46     </section>
47    
48     <section>
49     <title>Who Can Use overlays.gentoo.org?</title>
50     <body>
51    
52 tampakrap 1.19 <p>
53     Any Gentoo project, Gentoo developer, or Gentoo user can have their own overlay
54     hosted on *.overlays.gentoo.org, with the RSS feed from the changelog included
55     on <uri link="http://overlays.gentoo.org">the overlays.gentoo.org planet</uri>.
56     </p>
57    
58     <p>
59     Any User can download and use the contents of any hosted
60 stuart 1.1 overlay. If you choose, you can also give users write access to your
61 tampakrap 1.19 overlay.
62     </p>
63    
64 stuart 1.1 </body>
65     </section>
66    
67     <section>
68     <title>What Does overlays.gentoo.org Give Me?</title>
69     <body>
70 tampakrap 1.19
71     <p>
72     The *.overlays.gentoo.org service currently provides:
73     </p>
74    
75 stuart 1.1 <ul>
76 tampakrap 1.19 <li>
77     <uri link="http://trac.edgewall.com">Trac</uri>: a wiki with
78     integrated subversion browser), for quickly creating and maintaining
79     documentation about your Subversion based overlay
80     </li>
81     <li>
82     Publishing the changelog for your overlay on
83     <uri link="http://overlays.gentoo.org/">the o.g.o homepage</uri>, so
84     that everyone who's interested can see what's going on
85     </li>
86     <li>
87     <uri link="http://git.or.cz/gitwiki/Gitweb">Gitweb</uri>: provides
88     full-fledged web interface for viewing Git repositories.
89     </li>
90 stuart 1.1 </ul>
91    
92 tampakrap 1.19 <p>
93     ... all hosted on secure, backed-up Gentoo infrastructure, administered by
94     <uri link="/proj/en/infrastructure">the Gentoo Infrastructure team</uri>
95     (hardware / base OS) and <uri link="/proj/en/overlays">the Gentoo Overlays
96     team</uri> (wiki / VCS / ACLs).
97     </p>
98 stuart 1.1
99 tampakrap 1.19 <p>
100     Each overlay has separate authentication lists for Trac, Subversion and Git.
101 stuart 1.1 It's no problem at all to give someone write access to just Trac (e.g. for
102 tampakrap 1.19 writing documentation) without giving them write access to Subversion.
103     </p>
104    
105 stuart 1.1 </body>
106     </section>
107    
108     <section>
109     <title>Why Should We Use overlays.gentoo.org?</title>
110     <body>
111 tampakrap 1.19
112     <p>
113     You don't have to. You don't have to have an overlay at all, and if you do
114 stuart 1.1 have one, you are absolutely free to host your own overlay somewhere else.
115 tampakrap 1.19 You don't have to host an overlay on o.g.o for it to be considered "official".
116     </p>
117 stuart 1.1
118 tampakrap 1.19 <p>
119     The advantage of using overlays.gentoo.org is that we already have everything
120 stuart 1.1 setup for you. You don't need to admin your own server, or worry about
121 tampakrap 1.19 software upgrades. We take care of all of that for you.
122     </p>
123    
124 stuart 1.1 </body>
125     </section>
126    
127     <section>
128     <title>When Should We Not Use overlays.gentoo.org?</title>
129     <body>
130 tampakrap 1.19
131     <p>
132     The purpose of o.g.o is to help bridge the gap between developers and users.
133 stuart 1.1 Gentoo is a community-based distribution, and we believe that our users are
134 tampakrap 1.19 just as important a part of that community as developers are.
135     </p>
136 stuart 1.1
137 tampakrap 1.19 <p>
138     All of the overlays hosted on o.g.o are there for all users to download and
139 stuart 1.1 use. It's for users to make their own decision about what software they
140     install on their computers - and that includes choosing to use your overlay.
141 tampakrap 1.19 Some users will make bad decisions, and end up breaking their computer. They
142     may even end up blaming Gentoo as a result. That's okay; these people
143 stuart 1.1 probably go around blaming everyone but themselves for their own
144     mistakes anyway, and there's probably nothing you can do to change that.
145 tampakrap 1.19 But that still doesn't give any of us the right to choose for them.
146     </p>
147 stuart 1.1
148 tampakrap 1.19 <p>
149     Users are free (in fact, they are encouraged) to provide constructive
150 stuart 1.1 feedback about anything to do with Gentoo - including all of the overlays
151     hosted on o.g.o. That feedback can come via bugs.g.o, via email to your
152     project team or directly to you, via the forums, or via IRC. We're not
153     talking about genuinely abusive users; we have no time for those, and no-one
154 tampakrap 1.19 expects you to have any time for them either.
155     </p>
156 stuart 1.1
157 tampakrap 1.19 <warn>
158     If you're not happy with users using your overlay, and / or if you don't want
159 stuart 1.1 users bothering you about your overlay, then don't use o.g.o to host your
160 tampakrap 1.19 overlay, or remove your overlay from the overlays list (repositories.xml).
161     </warn>
162 stuart 1.1
163 tampakrap 1.19 <p>
164     o.g.o used to have restrictions of not being the $UPSTREAM for packages.
165 robbat2 1.13 This restriction has been adjusted. We do offer hosting as the $UPSTREAM now,
166     but only for packages that are Gentoo-specific or important to the running of
167     Gentoo. Other hosting may be more suitable, some services in this vein are:
168     <uri link="http://www.sourceforge.net/">SourceForge.net</uri>, <uri
169 tampakrap 1.19 link="http://www.berlios.de">Berlios</uri>, Patrick's <uri
170     link="http://www.gentooexperimental.org">GentooExperimental.org</uri>, <uri
171     link="http://www.github.com">GitHub</uri> or <uri link="http://www.gitorious.org">
172     Gitorious</uri>.
173     </p>
174    
175 stuart 1.1 </body>
176     </section>
177     </chapter>
178    
179     <chapter>
180     <title>Requesting An Overlay</title>
181    
182     <section>
183     <title>Introduction</title>
184     <body>
185 tampakrap 1.19 <p>There are three types of overlays: "project" overlays, "developer"
186     overlays and user overlays. The only difference between them is responsibility
187     and accountability.</p>
188    
189     <impo>
190     Before requesting an overlay, please make sure that you have read our
191     <uri link="/proj/en/overlays/policy.xml">Policy Document</uri>. It clearly sets
192     out what's allowed and what is not, and what your responsibilities will be.
193     </impo>
194 stuart 1.1
195     </body>
196     </section>
197    
198     <section>
199     <title>Project Overlays</title>
200     <body>
201    
202 tampakrap 1.19 <p>
203     "Project" overlays are overlays for official Gentoo projects. An example is
204     <uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.
205     </p>
206 stuart 1.1
207 tampakrap 1.19 <p>
208     An official Gentoo project is a project that has a project page on
209     www.gentoo.org, and that has an elected lead. (This definition comes from the
210     metastructure document). The project lead(s) are responsible for the project
211     overlay, including its contents, and any problems it causes other Gentoo projects
212     and developers.
213     </p>
214    
215     <p>
216     To request a SVN project overlay, the project's lead just needs to pop into
217 stuart 1.1 #gentoo-overlays on IRC and ask for an overlay to be created. Or, if he/she
218     prefers, drop an email to overlays@gentoo.org. We'll take care of the rest,
219     including granting write access to all the members of your project (as listed
220 tampakrap 1.19 on your project page).
221     </p>
222 stuart 1.1
223 tampakrap 1.19 <p>
224     To request a Git project overlay, just visit the <uri
225 robbat2 1.11 link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
226 tampakrap 1.21 setup instructions, emailing the completed template as directed.
227 tampakrap 1.19 </p>
228    
229     <p>
230     For an SVN request, we will:
231     </p>
232 robbat2 1.11
233 stuart 1.1 <ul>
234 tampakrap 1.19 <li>
235     create your overlay (trac site + svn)
236     </li>
237     <li>
238     add your overlay's RSS feed to the o.g.o homepage
239     </li>
240     <li>
241     create an o.g.o account for you if you don't already have one
242     </li>
243     <li>
244     give you write access to your overlay's Trac wiki and Subversion
245     repository
246     </li>
247     <li>
248     give write access to all project members who already have an o.g.o
249     account
250     </li>
251     </ul>
252    
253     <p>
254     For an Git request, we will:
255     </p>
256    
257     <ul>
258     <li>
259     create your overlay (git, gitweb, no trac)
260     </li>
261     <li>
262     add your overlay's RSS feed to the o.g.o homepage
263     </li>
264     <li>
265     create an git.o.g.o account for you if you don't already have one
266     </li>
267     <li>
268     give you write access to your overlays Git repository
269     </li>
270     <li>
271     give write access to all project members who already have an o.g.o account
272     </li>
273 robbat2 1.11 </ul>
274    
275 stuart 1.1 </body>
276     </section>
277    
278     <section>
279     <title>Developer Overlays</title>
280     <body>
281    
282 tampakrap 1.19 <p>
283     "Developer" overlays are overlays owned by individual Gentoo developers. One
284     example is <uri link="http://overlays.gentoo.org/dev/beandog">beandog's
285     overlay</uri>.
286     </p>
287 stuart 1.1
288 tampakrap 1.19 <p>
289     If you have an @gentoo.org email address, and you've passed the ebuild quiz,
290     then you can have your own developer overlay on o.g.o.
291     </p>
292 stuart 1.1
293 tampakrap 1.19 <p>
294     To request a SVN developer overlay, just pop into #gentoo-overlays on IRC
295 robbat2 1.11 and ask for an overlay to be created for you. Or, if you prefer, drop an email
296 tampakrap 1.19 to overlays@gentoo.org.
297     </p>
298 robbat2 1.11
299 tampakrap 1.19 <p>
300     To request a Git developer overlay, just visit the <uri
301 robbat2 1.11 link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
302 tampakrap 1.19 setup instructions, emailing the completed template as directed.
303     </p>
304    
305     <p>
306     For an SVN request, we will:
307     </p>
308 stuart 1.1
309     <ul>
310 tampakrap 1.19 <li>
311     create your overlay (trac site + svn)
312     </li>
313     <li>
314     add your overlay's RSS feed to the o.g.o homepage
315     </li>
316     <li>
317     create an o.g.o account for you if you don't have one already
318     </li>
319     <li>
320     give you write access to your overlay's Trac wiki and Subversion
321     repository
322     </li>
323 stuart 1.1 </ul>
324 robbat2 1.11
325 tampakrap 1.19 <p>
326     For an Git request, we will:
327     </p>
328    
329 robbat2 1.11 <ul>
330 tampakrap 1.19 <li>
331     create your overlay (git, gitweb, no trac)
332     </li>
333     <li>
334     add your overlay's RSS feed to the o.g.o homepage
335     </li>
336     <li>
337     create an git.o.g.o account for you if you don't already have one
338     </li>
339     <li>
340     give you write access to your overlays Git repository
341     </li>
342 robbat2 1.11 </ul>
343 tampakrap 1.19
344 stuart 1.1 </body>
345     </section>
346    
347     <section>
348     <title>A Word About Accounts</title>
349     <body>
350 tampakrap 1.19
351     <p>
352     Because o.g.o is designed to support a blend of both Gentoo developers and
353 stuart 1.1 Gentoo users, we don't create 'real' system-level accounts on the o.g.o host.
354 jokey 1.15 </p>
355 stuart 1.1
356     <impo>You do *not* have SSH access to o.g.o.</impo>
357 tampakrap 1.19
358 stuart 1.1 </body>
359     </section>
360     </chapter>
361    
362     <chapter>
363     <title>Working With Your Overlay</title>
364    
365     <section>
366     <title>Introduction</title>
367     <body>
368 tampakrap 1.19
369     <p>
370     You can access your overlay as soon as it has been created. Project and
371 stuart 1.1 developer overlays have different URLs, so that everyone can tell one from the
372 tampakrap 1.19 other, but otherwise they are identical in every way.
373     </p>
374 stuart 1.1
375 tampakrap 1.19 <p>
376     There are *no* read restrictions on overlays or wikis. Everyone has full
377 stuart 1.1 read access to all overlays and wikis. If you need a 'secret' overlay of some
378 tampakrap 1.19 kind, then o.g.o is not for you.
379     </p>
380    
381 stuart 1.1 </body>
382     </section>
383    
384     <section>
385     <title>Accessing Project Overlays</title>
386     <body>
387    
388 tampakrap 1.19 <p>
389     If your project overlay is called 'foo', your Trac wiki site will be
390     here: http://overlays.gentoo.org/proj/foo/
391     </p>
392    
393     <p>
394     To checkout your Subversion repository, use:
395     </p>
396 robbat2 1.10
397 tampakrap 1.19 <pre caption="Checkout your project overlay">
398     svn co https://overlays.gentoo.org/svn/proj/foo/</pre>
399    
400     <p>
401     While you may perform read-only actions via unsecure HTTP, you must perform
402     all commits via HTTPS. If you need to switch between modes, use:
403     </p>
404    
405     <pre caption="Switching your project overlay from HTTP to HTTPS">
406     svn sw --relocate http://overlays.gentoo.org/svn/proj/foo/
407     https://overlays.gentoo.org/svn/proj/foo/</pre>
408    
409     <p>
410     We maintain <uri link="http://overlays.gentoo.org/proj/">a full list of
411     project overlays hosted on overlays.gentoo.org</uri>.
412     </p>
413 stuart 1.1
414     </body>
415     </section>
416    
417     <section>
418     <title>Accessing Developer Overlays</title>
419     <body>
420    
421 tampakrap 1.19 <p>
422     If your Gentoo email address is 'foo@gentoo.org', your Trac wiki site will be
423     here: http://overlays.gentoo.org/dev/foo/
424     </p>
425 robbat2 1.10
426 tampakrap 1.19 <p>
427     To checkout your Subversion repository, use:
428     </p>
429    
430     <pre caption="Checkout your developer overlay">svn co
431     https://overlays.gentoo.org/svn/dev/foo/</pre>
432    
433     <p>
434     While you may perform read-only actions via unsecure HTTP, you must perform
435     all commits via HTTPS. If you need to switch between modes, use:
436     </p>
437    
438     <pre caption="Switching your developer overlay from HTTP to HTTPS">svn sw
439     --relocate http://overlays.gentoo.org/svn/dev/foo/ https://overlays.gentoo.org/svn/dev/foo/</pre>
440    
441     <p>
442     We maintain <uri link="http://overlays.gentoo.org/dev/">a full list of
443     developer overlays hosted on overlays.gentoo.org</uri>.
444     </p>
445 stuart 1.1
446     </body>
447     </section>
448    
449     <section>
450     <title>Getting Started With Trac</title>
451     <body>
452    
453 tampakrap 1.19 <p>
454     Your overlay comes with <uri link="http://trac.edgewall.com">Trac</uri>.
455     Trac is a wiki, a subversion repository browser, and a bug tracking system that's
456     very popular with open source developers.
457     </p>
458 stuart 1.1
459 tampakrap 1.19 <p>
460     We have disabled the bug tracking system in Trac. Use <uri
461     link="http://bugs.gentoo.org">Gentoo's bugzilla</uri> for bug tracking your
462     overlay.
463     </p>
464    
465     <p>
466     Your overlay's RSS feed - the one that is shown on <uri
467     link="http://overlays.gentoo.org">the o.g.o homepage</uri> - comes from Trac's
468     Timeline page or GitWeb's summary.
469     </p>
470 stuart 1.2
471 stuart 1.1 </body>
472     </section>
473    
474     <section>
475     <title>Getting Started With Subversion</title>
476     <body>
477 tampakrap 1.19
478 jokey 1.15 <p>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>
479 stuart 1.1
480 jokey 1.15 <p>If you have never used Subversion before, the online book is an excellent way to learn Subversion. You can buy it in dead-tree format too if you prefer.</p>
481 stuart 1.1
482 stuart 1.2 <p>Here are some basic commands to get you started.</p>
483 robbat2 1.10 <pre caption="Checking out your overlay">svn co https://overlays.gentoo.org/proj/php</pre>
484 stuart 1.2 <pre caption="Seeing which files need committing">svn status</pre>
485     <pre caption="Adding files to your overlay">svn add my.ebuild</pre>
486     <pre caption="Committing your changes">svn commit -m 'My changelog entry'</pre>
487 stuart 1.1
488     </body>
489     </section>
490    
491     <section>
492     <title>Layman</title>
493     <body>
494     <p>We are telling users to use layman to download and manage your overlay.
495     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>
496    
497 nightmorph 1.16 <p>
498     To get started with using layman, see <uri
499     link="http://layman.sourceforge.net/">the homepage documentation</uri>, the <uri
500     link="http://www.gentoo.org/news/en/gwn/20060522-newsletter.xml">Gentoo Weekly
501     News for 22nd May</uri> or read <c>man layman</c>.
502     </p>
503 stuart 1.1 </body>
504     </section>
505    
506     <section>
507     <title>Auto-Sync From Portage</title>
508     <body>
509     <p>Your packages in the Portage tree are always at risk of being changed without
510     you knowing about it in advance. Arch teams need to be able to keyword
511     packages (and fix arch-specific brokenness), the QA team fix perceived
512     standards violations, and occaisionally developers will edit packages that
513     they shouldn't.</p>
514    
515     <p>You need to make sure that the changes made in Portage aren't lost the next
516     time you copy your packages from your overlay back into Portage.</p>
517    
518     <p>The PHP team have solved this problem by automatically copying their packages
519     from Portage back into a 'portage' branch of their overlay every night. They
520 chtekk 1.9 can then use Subversion (or Trac's timeline) to see what has changed every day.</p>
521 stuart 1.1
522     </body>
523     </section>
524     </chapter>
525    
526     <chapter>
527 genstef 1.8 <title>Using git on overlays</title>
528    
529     <section>
530     <title>Initializing your overlay</title>
531     <body>
532     <p>Before uploading you need to locally create a git repository and add all items:</p>
533     <pre caption="go to your overlay">cd ~/my-overlay</pre>
534     <pre caption="create a new git repo">git init
535     git add .
536     git commit -m "populate overlay"</pre>
537 robbat2 1.11 <p>Note that this commit was only locally, now we get the server into the game.</p>
538     <pre caption="tell git the url">git remote add origin git+ssh://git@git.overlays.gentoo.org/(proj or dev)/(name)</pre>
539     <pre caption="finally get it up there">git push origin master</pre>
540 genstef 1.8 <p>Source: http://www.kernel.org/pub/software/scm/git/docs/tutorial.html</p>
541     </body></section>
542    
543     <section>
544     <title>Checking out the overlay with git</title>
545     <body>
546 robbat2 1.11 <pre caption="clone it!">git clone git://git@git.overlays.gentoo.org/(proj or dev)/(name)/</pre>
547 genstef 1.8 </body>
548     </section>
549     </chapter>
550    
551     <chapter>
552 stuart 1.1 <title>Giving Access To Your Overlay To Others</title>
553    
554     <section>
555     <title>Introduction</title>
556     <body>
557     <p>One of the key features of o.g.o is that people who do not have write access
558     to the Gentoo Portage package tree can have write access to one or more
559     overlays. Several Gentoo projects have found that this is a great way to train
560     and evaluate potential Gentoo developers in a safe environment.</p>
561     </body>
562     </section>
563    
564     <section>
565     <title>Project Overlays: Giving Write Access To Team Members</title>
566     <body>
567     <p>Any developer listed on a team's project page on www.g.o can have write
568     access to the team's overlay. The project lead can ask on their behalf, or
569     the developer can come and ask for access themselves.</p>
570    
571 tommy 1.23 <p>If the developer doesn't have an o.g.o account yet, he/she will need to open
572     a bug at <uri link="https://bugs.gentoo.org">Gentoo's bugzilla</uri> so that we
573     can create an account for them.</p>
574 stuart 1.1 </body>
575     </section>
576    
577     <section>
578     <title>Project Overlays: Giving Write Access To Other Gentoo
579     Developers</title>
580     <body>
581    
582     <p>Any Gentoo developer *not* listed on a team's project page on www.g.o can
583     have write access to the team's overlay. The request for write access must
584     come from a member of the team. It doesn't have to come from the project
585     lead.</p>
586    
587 tommy 1.23 <p>If the developer doesn't have an o.g.o account yet, he/she will need to open
588     a bug at <uri link="https://bugs.gentoo.org">Gentoo's bugzilla</uri> so that we
589     can create an account for them.</p>
590 stuart 1.1 </body>
591     </section>
592    
593     <section>
594     <title>Project Overlays: Giving Write Access To Gentoo Users</title>
595     <body>
596     <p>Any Gentoo user can have write access to the team's overlay. The request for
597     write access must come from one of the project's leads. You can request that
598     we give the user write access to Trac, to Subversion, or to both. (We will
599     assume that the request is for write access to both, unless you say
600     otherwise).</p>
601    
602     <p>We cannot accept these requests from anyone other than a project lead. If
603     your project only has the one lead, we recommend electing a second lead. If
604     your one and only lead is AWOL, consider electing a replacement :)</p>
605    
606 tommy 1.23 <p>If the user doesn't have an o.g.o account yet, he/she will need to open
607     a bug at <uri link="https://bugs.gentoo.org">Gentoo's bugzilla</uri> so
608     that we can create an account for them.</p>
609 stuart 1.1 </body>
610     </section>
611    
612     <section>
613     <title>Developer Overlays: Giving Write Access To Gentoo Developers</title>
614     <body>
615     <p>Any Gentoo developer can have write access to your developer overlay. The
616     developer can ask us directly; we will not give access until we've checked
617     with you. You can also ask us to give write access to any named
618     developer.</p>
619    
620 tommy 1.23 <p>If the developer doesn't have an o.g.o account yet, he/she will need to open
621     a bug at <uri link="https://bugs.gentoo.org">Gentoo's bugzilla</uri> so
622     that we can create an account for them.</p>
623 stuart 1.1 </body>
624     </section>
625    
626     <section>
627     <title>Developer Overlays: Giving Write Access To Gentoo Users</title>
628     <body>
629     <p>Any Gentoo user can have write access to your developer's overlay. The
630     request for write access must come from you. You can request that we give
631     the user write access just to Trac, just to Subversion, or to both. (We will
632     assume that the request is for write access to both unless you say
633     otherwise).</p>
634    
635     <p>We cannot accept these requests from anyone else other than you. If you find
636     yourself giving access to a lot of other people, it might be that you should
637     consider setting up a new project, and transfering your work there
638     instead.</p>
639    
640 tommy 1.23 <p>If the user doesn't have an o.g.o account yet, he/she will need to open
641     a bug at <uri link="https://bugs.gentoo.org">Gentoo's bugzilla</uri> so
642     that we can create an account for them.</p>
643 stuart 1.1 </body>
644     </section>
645     </chapter>
646    
647     <chapter>
648     <title>Accessing Someone Else's Overlay</title>
649    
650     <section>
651     <title>Using An Overlay</title>
652     <body>
653     <p>Everyone has full read access to every overlay. We recommend that you
654     use</p>
655     <pre caption="Install layman">
656     emerge layman
657 sping 1.17 echo 'source /var/lib/layman/layman.conf' &gt;&gt; /etc/make.conf
658 stuart 1.1 </pre>
659    
660 wrobel 1.6 <note>
661 sping 1.17 Layman will create "/var/lib/layman/make.conf" once you add
662 wrobel 1.7 your first overlay. But if you do not plan to install an overlay
663     immediately you should ensure that this file actually exists and
664     contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will
665 sping 1.18 complain. You can run "echo PORTDIR_OVERLAY='' >
666 sping 1.17 /var/lib/layman/make.conf" in order to have the file created
667 wrobel 1.7 correctly.
668 wrobel 1.6 </note>
669    
670 stuart 1.1 <p>After that, to view the list of overlays, use</p>
671    
672     <pre caption="List overlays that layman knows about">layman -L</pre>
673    
674     <p>To install an overlay, use</p>
675     <pre caption="Install an overlay">layman -a &lt;overlay-name&gt;</pre>
676    
677     <p>You can now install packages from the overlay.</p>
678     </body>
679     </section>
680    
681     <section>
682     <title>Requesting Write Access</title>
683     <body>
684     <p>If you want write access to a project overlay, contact a member of the
685     project team, and ask them for access. If they approve your request, they
686     will arrange for you to have write access, by contacting the Overlays
687     team.</p>
688    
689     <p>If you want write access to a developer's overlay, contact the developer
690     directly, and ask them for access. If they approve your request, they will
691     arrange for you to have write access, by contacting the Overlays team.</p>
692     </body>
693     </section>
694     </chapter>
695    
696     <chapter>
697     <title>Frequently Asked Questions</title>
698    
699     <section>
700     <title>o.g.o Administration</title>
701     <body>
702    
703     <p>Q: How do I contact the o.g.o admin staff?</p>
704     <ul>
705     <li>A: You can pop into #gentoo-overlays on IRC, and talk to us there. The
706     current staff are mostly in European timezones.</li>
707     <li>A: You can send an email to overlays@gentoo.org. Someone will answer you as
708     soon as possible.</li>
709     </ul>
710    
711     <p>Q: Why can't I edit the access control list directly?</p>
712     <ul>
713 jokey 1.15 <li>A: (SVN) The access control list currently lives in htpasswd format. Only o.g.o admin staff members have ssh access to the o.g.o box.</li>
714     <li>A: (Git) The access control list currently lives in the gitosis-admin repository, which is writable only by the o.g.o staff.</li>
715 stuart 1.1 </ul>
716     </body>
717     </section>
718    
719     <section>
720     <title>Security</title>
721     <body>
722     <p>Q: Is my overlay available via https?</p>
723     <ul>
724 stuart 1.4 <li>A: Yes, it is.</li>
725 stuart 1.1 </ul>
726     </body>
727     </section>
728    
729     <section>
730     <title>Multiple Overlays</title>
731     <body>
732    
733     <p>Q: Can I have multiple overlays?</p>
734     <ul>
735     <li>A: Yes, in a fashion. Inside your overlay, you can create
736     sub-directories, and put separate package trees inside those sub-directories.
737     Please take a look at the PHP project overlay for an example.</li>
738     </ul>
739     </body>
740     </section>
741    
742     <section>
743     <title>Importing Existing Overlays</title>
744     <body>
745     <p>Q: I already have an overlay, and I'd like to move it to o.g.o. How do I
746     go about doing that?</p>
747     <ul>
748     <li>A: Create a tarball of your subversion repository, and put it somewhere
749     where it can be downloaded via http. We'll download it and install it onto
750     o.g.o for you.</li>
751     </ul>
752     <note>Make sure you tar up your repository, and not a checkout!</note>
753    
754     <p>Q: I have an overlay, but it doesn't use Subversion. How do I go about
755     moving it to o.g.o?</p>
756     <ul>
757     <li>A: Ask us to create a new, empty overlay for you. You can then use 'svn
758     import' to import your files into the new overlay. You'll lose your history,
759     but that can't be helped.</li>
760     <li>A: Search the Internet, and see if there is a tool to convert from your
761     existing version control software to Subversion. If there is, use that, and
762     then we can help you move it to o.g.o.</li>
763     <li>A: If your version control software is used by Trac, and it can be used
764     over HTTP, come and help us add
765     support for your version control software on o.g.o.</li>
766     </ul>
767     </body>
768     </section>
769    
770     <section>
771     <title>"Official" Overlays</title>
772     <body>
773     <p>Q: When is an overlay considered "official"?</p>
774     <ul>
775     <li>A: An "official" overlay is an overlay managed by a Gentoo project (for
776     project overlays) or a Gentoo developer (for developer overlays).</li>
777     </ul>
778    
779     <p>Q: Does an overlay have to be on o.g.o to be "official"?</p>
780     <ul>
781     <li>A: No.</li>
782     </ul>
783     </body>
784     </section>
785     </chapter>
786     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20