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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.13 Revision 1.17
17<abstract>This guide helps developers understand how to use the Gentoo 17<abstract>This guide helps developers understand how to use the Gentoo
18Overlays service.</abstract> 18Overlays service.</abstract>
19 19
20<license/> 20<license/>
21 21
22<version>2.0</version> 22<version>2.3</version>
23<date>2008-10-12</date> 23<date>2009-01-18</date>
24 24
25<chapter> 25<chapter>
26<title>Introduction</title> 26<title>Introduction</title>
27 27
28<section> 28<section>
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> 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> 32</body>
33</section> 33</section>
34 34
35<section> 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> 36<title>Who Can Use overlays.gentoo.org?</title>
44<body> 37<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> 38<p>Any Gentoo project, or Gentoo developer, can have their own overlay hosted on (git.)overlays.gentoo.org, with the RSS feed from the changelog included on <uri link="http://overlays.gentoo.org">the overlays.gentoo.org planet</uri>.</p>
46 39
47<p>Any Gentoo staff member or user (ie, anyone who doesn't have write access to 40<p>Any User can download and use the contents of any hosted
48the main Portage package tree) can download and use the contents of any hosted
49overlay. If you choose, you can also give users write access to your 41overlay. If you choose, you can also give users write access to your
50overlay.</p> 42overlay.</p>
51</body> 43</body>
52</section> 44</section>
53 45
54<section> 46<section>
55<title>What Does overlays.gentoo.org Give Me?</title> 47<title>What Does overlays.gentoo.org Give Me?</title>
56<body> 48<body>
57<p>The overlays.gentoo.org service currently provides:</p> 49<p>The (git.)overlays.gentoo.org service currently provides:</p>
58<ul> 50<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> 51<li><uri link="http://trac.edgewall.com">Trac</uri> (a wiki w/ integrated subversion browser), for quickly creating and maintaining documentation about your Subversion based overlay</li>
60<li><uri link="http://subversion.tigris.org">Subversion</uri> - a centralised version control system</li>
61<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> 52<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<li><uri link="http://git.or.cz">Git</uri> - Fast Version Control System</li>
63<li><uri link="http://git.or.cz/gitwiki/Gitweb">gitweb</uri> - provides full-fledged web interface for viewing Git repositories.</li> 53<li><uri link="http://git.or.cz/gitwiki/Gitweb">gitweb</uri> - provides full-fledged web interface for viewing Git repositories.</li>
64</ul> 54</ul>
65 55
66<p>... all hosted on secure, backed-up Gentoo infrastructure, administered by 56<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> 57<uri link="/proj/en/infrastructure">the Gentoo Infrastructure team</uri> (hardware / base OS) and <uri link="/proj/en/overlays">the Gentoo Overlays team</uri>
140</section> 130</section>
141 131
142<section> 132<section>
143<title>Project Overlays</title> 133<title>Project Overlays</title>
144<body> 134<body>
145<p>"Project" overlays are overlays for official Gentoo projects. A good 135<p>"Project" overlays are overlays for official Gentoo projects. An example is <uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.</p>
146example is <uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.</p>
147 136
148<p>An official Gentoo project is a project that has a project page on 137<p>An official Gentoo project is a project that has a project page on
149www.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 138www.gentoo.org, and that has an elected lead. (This definition comes from the
150metastructure document</uri>, which is Gentoo's governing document). The project 139metastructure document). The project lead(s) are responsible for the project overlay, including its contents, and any problems it causes other Gentoo projects and developers.</p>
151lead(s) are responsible for the project overlay, including its contents, and
152any problems it causes other Gentoo projects and developers.</p>
153 140
154<p>To request a SVN project overlay, the project's lead just needs to pop into 141<p>To request a SVN project overlay, the project's lead just needs to pop into
155#gentoo-overlays on IRC and ask for an overlay to be created. Or, if he/she 142#gentoo-overlays on IRC and ask for an overlay to be created. Or, if he/she
156prefers, drop an email to overlays@gentoo.org. We'll take care of the rest, 143prefers, drop an email to overlays@gentoo.org. We'll take care of the rest,
157including granting write access to all the members of your project (as listed 144including granting write access to all the members of your project (as listed
168<li>create an o.g.o account for you if you don't already have one</li> 155<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 156<li>give you write access to your overlay's Trac wiki and Subversion
170repository</li> 157repository</li>
171<li>give write access to all project members who already have an o.g.o 158<li>give write access to all project members who already have an o.g.o
172account</li> 159account</li>
173<li>contact all of the other project members, and sort out their access</li>
174</ul> 160</ul>
175 161
176<p>For an Git request, we will:</p> 162<p>For an Git request, we will:</p>
177<ul> 163<ul>
178<li>create your overlay (git, gitweb, no trac)</li> 164<li>create your overlay (git, gitweb, no trac)</li>
179<li>add your overlay's RSS feed to the o.g.o homepage</li> 165<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> 166<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> 167<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> 168<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> 169</ul>
185
186 170
187</body> 171</body>
188</section> 172</section>
189 173
190<section> 174<section>
191<title>Developer Overlays</title> 175<title>Developer Overlays</title>
192<body> 176<body>
193 177
194<p>"Developer" overlays are overlays owned by individual Gentoo developers. One 178<p>"Developer" overlays are overlays owned by individual Gentoo developers. One
195example is <uri link="http://overlays.gentoo.org/dev/tcort">tcort's overlay</uri>.</p> 179 example is <uri link="http://overlays.gentoo.org/dev/beandog">beandog's overlay</uri>.</p>
196 180
197<p>If you have an @gentoo.org email address, and you've passed the ebuild quiz, 181<p>If you have an @gentoo.org email address, and you've passed the ebuild quiz,
198then you can have your own developer overlay on o.g.o.</p> 182then you can have your own developer overlay on o.g.o.</p>
199 183
200<p>To request a SVN developer overlay, just pop into #gentoo-overlays on IRC 184<p>To request a SVN developer overlay, just pop into #gentoo-overlays on IRC
227<section> 211<section>
228<title>A Word About Accounts</title> 212<title>A Word About Accounts</title>
229<body> 213<body>
230<p>Because o.g.o is designed to support a blend of both Gentoo developers and 214<p>Because o.g.o is designed to support a blend of both Gentoo developers and
231Gentoo users, we don't create 'real' system-level accounts on the o.g.o host. 215Gentoo users, we don't create 'real' system-level accounts on the o.g.o host.
232All access is currently through Apache, and is managed by Apache htpasswd and 216</p>
233htgroup files.</p>
234 217
235<impo>You do *not* have SSH access to o.g.o.</impo> 218<impo>You do *not* have SSH access to o.g.o.</impo>
236</body> 219</body>
237</section> 220</section>
238</chapter> 221</chapter>
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 276<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
294very popular with open source developers.</p> 277very popular with open source developers.</p>
295 278
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> 279<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 280
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> 281<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 or GitWeb's summary.</p>
299
300<p>We have installed several Trac plugins, which we hope will make your wiki even
301more useful to you. If you come across any additional plugins that you'd like
302to see installed, please let us know, and we'll take a look at them.</p>
303
304<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 282
318</body> 283</body>
319</section> 284</section>
320 285
321<section> 286<section>
322<title>Getting Started With Subversion</title> 287<title>Getting Started With Subversion</title>
323<body> 288<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> 289<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>
325 290
326<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> 291<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>
327 292
328<p>Here are some basic commands to get you started.</p> 293<p>Here are some basic commands to get you started.</p>
329<pre caption="Checking out your overlay">svn co https://overlays.gentoo.org/proj/php</pre> 294<pre caption="Checking out your overlay">svn co https://overlays.gentoo.org/proj/php</pre>
330<pre caption="Seeing which files need committing">svn status</pre> 295<pre caption="Seeing which files need committing">svn status</pre>
331<pre caption="Adding files to your overlay">svn add my.ebuild</pre> 296<pre caption="Adding files to your overlay">svn add my.ebuild</pre>
338<title>Layman</title> 303<title>Layman</title>
339<body> 304<body>
340<p>We are telling users to use layman to download and manage your overlay. 305<p>We are telling users to use layman to download and manage your overlay.
341layman 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> 306layman 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 307
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> 308<p>
309To get started with using layman, see <uri
310link="http://layman.sourceforge.net/">the homepage documentation</uri>, the <uri
311link="http://www.gentoo.org/news/en/gwn/20060522-newsletter.xml">Gentoo Weekly
312News for 22nd May</uri> or read <c>man layman</c>.
313</p>
344</body> 314</body>
345</section> 315</section>
346 316
347<section> 317<section>
348<title>Auto-Sync From Portage</title> 318<title>Auto-Sync From Portage</title>
397<body> 367<body>
398<p>One of the key features of o.g.o is that people who do not have write access 368<p>One of the key features of o.g.o is that people who do not have write access
399to the Gentoo Portage package tree can have write access to one or more 369to the Gentoo Portage package tree can have write access to one or more
400overlays. Several Gentoo projects have found that this is a great way to train 370overlays. Several Gentoo projects have found that this is a great way to train
401and evaluate potential Gentoo developers in a safe environment.</p> 371and 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
404overlays.gentoo.org. We will provide a web-based tool for managing the access
405control lists at a later date. But, for now, if you need a change made,
406please drop by #gentoo-overlays on IRC for assistance.</p>
407</body> 372</body>
408</section> 373</section>
409 374
410<section> 375<section>
411<title>Project Overlays: Giving Write Access To Team Members</title> 376<title>Project Overlays: Giving Write Access To Team Members</title>
493<body> 458<body>
494<p>Everyone has full read access to every overlay. We recommend that you 459<p>Everyone has full read access to every overlay. We recommend that you
495use</p> 460use</p>
496<pre caption="Install layman"> 461<pre caption="Install layman">
497 emerge layman 462 emerge layman
498 echo 'source /usr/portage/local/layman/layman.conf' &gt;&gt; /etc/make.conf 463 echo 'source /var/lib/layman/layman.conf' &gt;&gt; /etc/make.conf
499</pre> 464</pre>
500 465
501<note> 466<note>
502Layman will create "/usr/portage/local/layman/make.conf" once you add 467Layman will create "/var/lib/layman/make.conf" once you add
503your first overlay. But if you do not plan to install an overlay 468your first overlay. But if you do not plan to install an overlay
504immediately you should ensure that this file actually exists and 469immediately you should ensure that this file actually exists and
505contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will 470contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will
506complain. You can run "echo PORTDIR_OVERLAY=\"\" > 471complain. You can run "echo PORTDIR_OVERLAY=\"\" >
507/usr/portage/local/layman/make.conf" in order to have the file created 472/var/lib/layman/make.conf" in order to have the file created
508correctly. 473correctly.
509</note> 474</note>
510 475
511<p>After that, to view the list of overlays, use</p> 476<p>After that, to view the list of overlays, use</p>
512 477
549 soon as possible.</li> 514 soon as possible.</li>
550</ul> 515</ul>
551 516
552<p>Q: Why can't I edit the access control list directly?</p> 517<p>Q: Why can't I edit the access control list directly?</p>
553<ul> 518<ul>
554<li>A: (SVN) The access control list currently lives in htpasswd / htgroup files used 519<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>
555 by Apache. Only o.g.o admin staff have ssh access into the o.g.o box.</li>
556<li>A: (Git) The access control list currently lives in the gitosis-admin repository, 520<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>
557 which is writable only by the o.g.o staff.</li>
558</ul> 521</ul>
559</body> 522</body>
560</section> 523</section>
561 524
562<section> 525<section>

Legend:
Removed from v.1.13  
changed lines
  Added in v.1.17

  ViewVC Help
Powered by ViewVC 1.1.20