/[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.12 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>
112 102
113<warn>If you're not happy with users using your overlay, and / or if you don't want 103<warn>If you're not happy with users using your overlay, and / or if you don't want
114users bothering you about your overlay, then don't use o.g.o to host your 104users bothering you about your overlay, then don't use o.g.o to host your
115overlay.</warn> 105overlay.</warn>
116 106
117<p>The other thing we need to say is that o.g.o is for hosting overlays. You 107<p>o.g.o used to have restrictions of not being the $UPSTREAM for packages.
118can't use it to be $UPSTREAM for your packages. If that's the kind of hosting 108This restriction has been adjusted. We do offer hosting as the $UPSTREAM now,
119you 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 109but only for packages that are Gentoo-specific or important to the running of
110Gentoo. Other hosting may be more suitable, some services in this vein are:
111<uri link="http://www.sourceforge.net/">SourceForge.net</uri>, <uri
112link="http://www.berlios.de">Berlios</uri>, or Patrick's <uri
120Patrick's <uri link="http://www.gentooexperimental.org">GentooExperimental.org</uri>.</p> 113link="http://www.gentooexperimental.org">GentooExperimental.org</uri>.</p>
121</body> 114</body>
122</section> 115</section>
123</chapter> 116</chapter>
124 117
125<chapter> 118<chapter>
137</section> 130</section>
138 131
139<section> 132<section>
140<title>Project Overlays</title> 133<title>Project Overlays</title>
141<body> 134<body>
142<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>
143example is <uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.</p>
144 136
145<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
146www.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
147metastructure 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>
148lead(s) are responsible for the project overlay, including its contents, and
149any problems it causes other Gentoo projects and developers.</p>
150 140
151<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
152#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
153prefers, 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,
154including 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
165<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>
166<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
167repository</li> 157repository</li>
168<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
169account</li> 159account</li>
170<li>contact all of the other project members, and sort out their access</li>
171</ul> 160</ul>
172 161
173<p>For an Git request, we will:</p> 162<p>For an Git request, we will:</p>
174<ul> 163<ul>
175<li>create your overlay (git, gitweb, no trac)</li> 164<li>create your overlay (git, gitweb, no trac)</li>
176<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>
177<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>
178<li>give you write access to your overlays Git repository</li> 167<li>give you write access to your overlays Git repository</li>
179<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>
180<li>contact all of the other project members, and sort out their access</li>
181</ul> 169</ul>
182
183 170
184</body> 171</body>
185</section> 172</section>
186 173
187<section> 174<section>
188<title>Developer Overlays</title> 175<title>Developer Overlays</title>
189<body> 176<body>
190 177
191<p>"Developer" overlays are overlays owned by individual Gentoo developers. One 178<p>"Developer" overlays are overlays owned by individual Gentoo developers. One
192example 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>
193 180
194<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,
195then 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>
196 183
197<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
224<section> 211<section>
225<title>A Word About Accounts</title> 212<title>A Word About Accounts</title>
226<body> 213<body>
227<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
228Gentoo 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.
229All access is currently through Apache, and is managed by Apache htpasswd and 216</p>
230htgroup files.</p>
231 217
232<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>
233</body> 219</body>
234</section> 220</section>
235</chapter> 221</chapter>
290<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
291very popular with open source developers.</p> 277very popular with open source developers.</p>
292 278
293<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>
294 280
295<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>
296
297<p>We have installed several Trac plugins, which we hope will make your wiki even
298more useful to you. If you come across any additional plugins that you'd like
299to see installed, please let us know, and we'll take a look at them.</p>
300
301<ul>
302<li><e>LayOnTrac</e> - lists the packages from the overlay.</li>
303<li><uri link="http://muness.textdriven.com/trac/wiki/tags/Setup">TracTags</uri> - displays a tag cloud</li>
304<li><uri link="http://trac.edgewall.org/wiki/WebAdmin">TracWebAdmin</uri> - provides web-based admin panel for Trac</li>
305</ul>
306
307<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>
308
309<ul>
310<li><uri link="http://trac-hacks.org/wiki/AddCommentMacro">AddComment</uri> - allows visitors to add comments to the bottom of your pages</li>
311<li><uri link="http://trac-hacks.org/wiki/FootNoteMacro">FootNote</uri> - adds support for adding footnotes to a page</li>
312<li><uri link="http://trac-hacks.org/wiki/TocMacro">TOC</uri> - adds support for publishing a Table of Contents on a page</li>
313</ul>
314 282
315</body> 283</body>
316</section> 284</section>
317 285
318<section> 286<section>
319<title>Getting Started With Subversion</title> 287<title>Getting Started With Subversion</title>
320<body> 288<body>
321<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>
322 290
323<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>
324 292
325<p>Here are some basic commands to get you started.</p> 293<p>Here are some basic commands to get you started.</p>
326<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>
327<pre caption="Seeing which files need committing">svn status</pre> 295<pre caption="Seeing which files need committing">svn status</pre>
328<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>
335<title>Layman</title> 303<title>Layman</title>
336<body> 304<body>
337<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.
338layman 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>
339 307
340<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>
341</body> 314</body>
342</section> 315</section>
343 316
344<section> 317<section>
345<title>Auto-Sync From Portage</title> 318<title>Auto-Sync From Portage</title>
394<body> 367<body>
395<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
396to 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
397overlays. 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
398and evaluate potential Gentoo developers in a safe environment.</p> 371and evaluate potential Gentoo developers in a safe environment.</p>
399
400<p>At the moment, only the Overlays team can update the access control lists for
401overlays.gentoo.org. We will provide a web-based tool for managing the access
402control lists at a later date. But, for now, if you need a change made,
403please drop by #gentoo-overlays on IRC for assistance.</p>
404</body> 372</body>
405</section> 373</section>
406 374
407<section> 375<section>
408<title>Project Overlays: Giving Write Access To Team Members</title> 376<title>Project Overlays: Giving Write Access To Team Members</title>
490<body> 458<body>
491<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
492use</p> 460use</p>
493<pre caption="Install layman"> 461<pre caption="Install layman">
494 emerge layman 462 emerge layman
495 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
496</pre> 464</pre>
497 465
498<note> 466<note>
499Layman will create "/usr/portage/local/layman/make.conf" once you add 467Layman will create "/var/lib/layman/make.conf" once you add
500your 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
501immediately you should ensure that this file actually exists and 469immediately you should ensure that this file actually exists and
502contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will 470contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will
503complain. You can run "echo PORTDIR_OVERLAY=\"\" > 471complain. You can run "echo PORTDIR_OVERLAY=\"\" >
504/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
505correctly. 473correctly.
506</note> 474</note>
507 475
508<p>After that, to view the list of overlays, use</p> 476<p>After that, to view the list of overlays, use</p>
509 477
546 soon as possible.</li> 514 soon as possible.</li>
547</ul> 515</ul>
548 516
549<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>
550<ul> 518<ul>
551<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>
552 by Apache. Only o.g.o admin staff have ssh access into the o.g.o box.</li>
553<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>
554 which is writable only by the o.g.o staff.</li>
555</ul> 521</ul>
556</body> 522</body>
557</section> 523</section>
558 524
559<section> 525<section>

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

  ViewVC Help
Powered by ViewVC 1.1.20