/[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.7 Revision 1.15
3 3
4<guide link="/proj/en/overlays/devguide.xml"> 4<guide link="/proj/en/overlays/devguide.xml">
5<title>Gentoo Overlays: Developers' Guide</title> 5<title>Gentoo Overlays: Developers' Guide</title>
6 6
7<author title="Author"> 7<author title="Author">
8 <mail link="stuart@gentoo.org">Stuart Herbert</mail> 8 <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>
9</author> 15</author>
10 16
11<abstract>This guide helps developers understand how to use the Gentoo 17<abstract>This guide helps developers understand how to use the Gentoo
12Overlays service.</abstract> 18Overlays service.</abstract>
13 19
14<license/> 20<license/>
15 21
16<version>1.0</version> 22<version>2.2</version>
17<date>2006-07-29</date> 23<date>2008-10-30</date>
18 24
19<chapter> 25<chapter>
20<title>Introduction</title> 26<title>Introduction</title>
21 27
22<section> 28<section>
25<p>This document has been written for Gentoo developers and Gentoo staff members. If you are a Gentoo user, or you just want to start downloading and using overlays, please see <uri link="/proj/en/overlays/userguide.xml">the Gentoo Overlays User Guide</uri> instead.</p> 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>
26</body> 32</body>
27</section> 33</section>
28 34
29<section> 35<section>
30<title>What is overlays.gentoo.org?</title>
31<body>
32<p><uri link="http://overlays.gentoo.org">overlays.gentoo.org</uri> provides social workspaces to allow Gentoo projects, developers and users to collaborate together on tomorrow's Gentoo packages. We do this by hosting overlays for Gentoo projects, and overlays for Gentoo developers.</p>
33</body>
34</section>
35
36<section>
37<title>Who Can Use overlays.gentoo.org?</title> 36<title>Who Can Use overlays.gentoo.org?</title>
38<body> 37<body>
39<p>Any Gentoo project, or Gentoo developer, can have their own overlay hosted on overlays.gentoo.org, with the RSS feed from the changelog included on <uri link="http://overlays.gentoo.org">the overlays.gentoo.org homepage</uri>.</p> 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>
40 39
41<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
42the main Portage package tree) can download and use the contents of any hosted
43overlay. 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
44overlay.</p> 42overlay.</p>
45</body> 43</body>
46</section> 44</section>
47 45
48<section> 46<section>
49<title>What Does overlays.gentoo.org Give Me?</title> 47<title>What Does overlays.gentoo.org Give Me?</title>
50<body> 48<body>
51<p>The overlays.gentoo.org service currently provides:</p> 49<p>The (git.)overlays.gentoo.org service currently provides:</p>
52<ul> 50<ul>
53<li><uri link="http://trac.edgewall.com">Trac</uri> (a wiki w/ integrated subversion browser), for quickly creating and maintaining documentation about your overlay</li> 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>
54<li><uri link="http://subversion.tigris.org">Subversion</uri> - a centralised version control system (distributed version control systems will be supported in future)</li>
55<li>Publishing the changelog for your overlay on <uri link="http://overlays.gentoo.org/">the o.g.o homepage</uri>, so that everyone who's interested can see what's going on</li> 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>
53<li><uri link="http://git.or.cz/gitwiki/Gitweb">gitweb</uri> - provides full-fledged web interface for viewing Git repositories.</li>
56</ul> 54</ul>
57 55
58<p>... all hosted on secure, backed-up Gentoo infrastructure, administered by 56<p>... all hosted on secure, backed-up Gentoo infrastructure, administered by
59<uri link="/proj/en/infrastructure">the Gentoo Infrastructure team</uri> (hardware / base OS) and <uri link="/proj/en/overlays">the Gentoo Overlays team</uri> 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>
60(wiki / VCS / ACLs).</p> 58(wiki / VCS / ACLs).</p>
61 59
62<p>Each overlay has separate authentication lists for Trac and for Subversion. 60<p>Each overlay has separate authentication lists for Trac, Subversion and Git.
63It's no problem at all to give someone write access to just Trac (e.g. for 61It's no problem at all to give someone write access to just Trac (e.g. for
64writing documentation) without giving them write access to Subversion.</p> 62writing documentation) without giving them write access to Subversion.</p>
65</body> 63</body>
66</section> 64</section>
67 65
104 102
105<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
106users 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
107overlay.</warn> 105overlay.</warn>
108 106
109<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.
110can'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,
111you 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
112Patrick's <uri link="http://www.gentooexperimental.org">GentooExperimental.org</uri>.</p> 113link="http://www.gentooexperimental.org">GentooExperimental.org</uri>.</p>
113</body> 114</body>
114</section> 115</section>
115</chapter> 116</chapter>
116 117
117<chapter> 118<chapter>
129</section> 130</section>
130 131
131<section> 132<section>
132<title>Project Overlays</title> 133<title>Project Overlays</title>
133<body> 134<body>
134<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>
135example is <uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.</p>
136 136
137<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
138www.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
139metastructure 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>
140lead(s) are responsible for the project overlay, including its contents, and
141any problems it causes other Gentoo projects and developers.</p>
142 140
143<p>To request a 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
144#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
145prefers, 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,
146including 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
147on your project page).</p> 145on your project page).</p>
148 146
149<p>We will:</p> 147<p>To request a Git project overlay, just visit the <uri
148link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
149setup instructions, emailing the completed template as directed.</p>
150
151<p>For an SVN request, we will:</p>
150<ul> 152<ul>
151<li>create your overlay (trac site + svn)</li> 153<li>create your overlay (trac site + svn)</li>
152<li>add your overlay's RSS feed to the o.g.o homepage</li> 154<li>add your overlay's RSS feed to the o.g.o homepage</li>
153<li>create an o.g.o account for you if you don't already have one</li> 155<li>create an o.g.o account for you if you don't already have one</li>
154<li>give you write access to your overlay's Trac wiki and Subversion 156<li>give you write access to your overlay's Trac wiki and Subversion
155repository</li> 157repository</li>
156<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
157account</li> 159account</li>
158<li>contact all of the other project members, and sort out their access</li> 160</ul>
161
162<p>For an Git request, we will:</p>
159</ul> 163<ul>
164<li>create your overlay (git, gitweb, no trac)</li>
165<li>add your overlay's RSS feed to the o.g.o homepage</li>
166<li>create an git.o.g.o account for you if you don't already have one</li>
167<li>give you write access to your overlays Git repository</li>
168<li>give write access to all project members who already have an o.g.o account</li>
169</ul>
170
160</body> 171</body>
161</section> 172</section>
162 173
163<section> 174<section>
164<title>Developer Overlays</title> 175<title>Developer Overlays</title>
165<body> 176<body>
166 177
167<p>"Developer" overlays are overlays owned by individual Gentoo developers. One 178<p>"Developer" overlays are overlays owned by individual Gentoo developers. One
168example 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>
169 180
170<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,
171then 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>
172 183
173<p>To request a developer overlay, just pop into #gentoo-overlays on IRC and ask 184<p>To request a SVN developer overlay, just pop into #gentoo-overlays on IRC
174for an overlay to be created for you. Or, if you prefer, drop an email to 185and ask for an overlay to be created for you. Or, if you prefer, drop an email
175overlays@gentoo.org.</p> 186to overlays@gentoo.org.</p>
176 187
177<p>We will:</p> 188<p>To request a Git developer overlay, just visit the <uri
189link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
190setup instructions, emailing the completed template as directed.</p>
191
192<p>For an SVN request, we will:</p>
178<ul> 193<ul>
179<li>create your overlay (trac site + svn)</li> 194<li>create your overlay (trac site + svn)</li>
180<li>add your overlay's RSS feed to the o.g.o homepage</li> 195<li>add your overlay's RSS feed to the o.g.o homepage</li>
181<li>create an o.g.o account for you if you don't have one already</li> 196<li>create an o.g.o account for you if you don't have one already</li>
182<li>give you write access to your overlay's Trac wiki and Subversion 197<li>give you write access to your overlay's Trac wiki and Subversion
183repository</li> 198repository</li>
184</ul> 199</ul>
200
201<p>For an Git request, we will:</p>
202<ul>
203<li>create your overlay (git, gitweb, no trac)</li>
204<li>add your overlay's RSS feed to the o.g.o homepage</li>
205<li>create an git.o.g.o account for you if you don't already have one</li>
206<li>give you write access to your overlays Git repository</li>
207</ul>
185</body> 208</body>
186</section> 209</section>
187 210
188<section> 211<section>
189<title>A Word About Accounts</title> 212<title>A Word About Accounts</title>
190<body> 213<body>
191<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
192Gentoo 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.
193All access is currently through Apache, and is managed by Apache htpasswd and 216</p>
194htgroup files.</p>
195 217
196<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>
197</body> 219</body>
198</section> 220</section>
199</chapter> 221</chapter>
219<body> 241<body>
220<p>If your project overlay is called 'foo', your Trac wiki site will be 242<p>If your project overlay is called 'foo', your Trac wiki site will be
221here: http://overlays.gentoo.org/proj/foo/</p> 243here: http://overlays.gentoo.org/proj/foo/</p>
222 244
223<p>To checkout your Subversion repository, use:</p> 245<p>To checkout your Subversion repository, use:</p>
224<pre caption="Checkout your project overlay">svn co http://overlays.gentoo.org/svn/proj/foo/</pre> 246<pre caption="Checkout your project overlay">svn co https://overlays.gentoo.org/svn/proj/foo/</pre>
247
248<p>While you may perform read-only actions via unsecure HTTP, you must perform
249all commits via HTTPS. If you need to switch between modes, use:</p>
250<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>
225 251
226<p>We maintain <uri link="http://overlays.gentoo.org/proj/">a full list of project overlays hosted on overlays.gentoo.org</uri>.</p> 252<p>We maintain <uri link="http://overlays.gentoo.org/proj/">a full list of project overlays hosted on overlays.gentoo.org</uri>.</p>
227</body> 253</body>
228</section> 254</section>
229 255
232<body> 258<body>
233<p>If your Gentoo email address is 'foo@gentoo.org', your Trac wiki site will be 259<p>If your Gentoo email address is 'foo@gentoo.org', your Trac wiki site will be
234here: http://overlays.gentoo.org/dev/foo/</p> 260here: http://overlays.gentoo.org/dev/foo/</p>
235 261
236<p>To checkout your Subversion repository, use:</p> 262<p>To checkout your Subversion repository, use:</p>
237<pre caption="Checkout your developer overlay">svn co http://overlays.gentoo.org/svn/dev/foo/</pre> 263<pre caption="Checkout your developer overlay">svn co https://overlays.gentoo.org/svn/dev/foo/</pre>
264
265<p>While you may perform read-only actions via unsecure HTTP, you must perform
266all commits via HTTPS. If you need to switch between modes, use:</p>
267<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>
238 268
239<p>We maintain <uri link="http://overlays.gentoo.org/dev/">a full list of developer overlays hosted on overlays.gentoo.org</uri>.</p> 269<p>We maintain <uri link="http://overlays.gentoo.org/dev/">a full list of developer overlays hosted on overlays.gentoo.org</uri>.</p>
240</body> 270</body>
241</section> 271</section>
242 272
246<p>Your overlay comes with <uri link="http://trac.edgewall.com">Trac</uri>. Trac is a wiki, a subversion repository browser, and a bug tracking system that's 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
247very popular with open source developers.</p> 277very popular with open source developers.</p>
248 278
249<p>We have disabled the bug tracking system in Trac. Use <uri link="http://bugs.gentoo.org">Gentoo's bugzilla</uri> for bug tracking your overlay.</p> 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>
250 280
251<p>Your overlay's RSS feed - the one that is shown on <uri link="http://overlays.gentoo.org">the o.g.o homepage</uri> - comes from Trac's Timeline page.</p> 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>
252
253<p>We have installed several Trac plugins, which we hope will make your wiki even
254more useful to you. If you come across any additional plugins that you'd like
255to see installed, please let us know, and we'll take a look at them.</p>
256
257<ul>
258<li><e>LayOnTrac</e> - lists the packages from the overlay.</li>
259<li><uri link="http://muness.textdriven.com/trac/wiki/tags/Setup">TracTags</uri> - displays a tag cloud</li>
260<li><uri link="http://trac.edgewall.org/wiki/WebAdmin">TracWebAdmin</uri> - provides web-based admin panel for Trac</li>
261</ul>
262
263<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>
264
265<ul>
266<li><uri link="http://trac-hacks.org/wiki/AddCommentMacro">AddComment</uri> - allows visitors to add comments to the bottom of your pages</li>
267<li><uri link="http://trac-hacks.org/wiki/FootNoteMacro">FootNote</uri> - adds support for adding footnotes to a page</li>
268<li><uri link="http://trac-hacks.org/wiki/TocMacro">TOC</uri> - adds support for publishing a Table of Contents on a page</li>
269</ul>
270 282
271</body> 283</body>
272</section> 284</section>
273 285
274<section> 286<section>
275<title>Getting Started With Subversion</title> 287<title>Getting Started With Subversion</title>
276<body> 288<body>
277<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>
278 290
279<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>
280 292
281<p>Here are some basic commands to get you started.</p> 293<p>Here are some basic commands to get you started.</p>
282<pre caption="Checking out your overlay">svn co http://overlays.gentoo.org/proj/php</pre> 294<pre caption="Checking out your overlay">svn co https://overlays.gentoo.org/proj/php</pre>
283<pre caption="Seeing which files need committing">svn status</pre> 295<pre caption="Seeing which files need committing">svn status</pre>
284<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>
285<pre caption="Committing your changes">svn commit -m 'My changelog entry'</pre> 297<pre caption="Committing your changes">svn commit -m 'My changelog entry'</pre>
286 298
287</body> 299</body>
309<p>You need to make sure that the changes made in Portage aren't lost the next 321<p>You need to make sure that the changes made in Portage aren't lost the next
310time you copy your packages from your overlay back into Portage.</p> 322time you copy your packages from your overlay back into Portage.</p>
311 323
312<p>The PHP team have solved this problem by automatically copying their packages 324<p>The PHP team have solved this problem by automatically copying their packages
313from Portage back into a 'portage' branch of their overlay every night. They 325from Portage back into a 'portage' branch of their overlay every night. They
314can then use Subversion (or Trac's timeline) to see what has changed every 326can then use Subversion (or Trac's timeline) to see what has changed every day.</p>
315day. If you'd like to have this feature added to your overlay, contact CHTEKK.</p>
316 327
328</body>
329</section>
330</chapter>
331
332<chapter>
333<title>Using git on overlays</title>
334
335<section>
336<title>Initializing your overlay</title>
337<body>
338<p>Before uploading you need to locally create a git repository and add all items:</p>
339<pre caption="go to your overlay">cd ~/my-overlay</pre>
340<pre caption="create a new git repo">git init
341git add .
342git commit -m "populate overlay"</pre>
343<p>Note that this commit was only locally, now we get the server into the game.</p>
344<pre caption="tell git the url">git remote add origin git+ssh://git@git.overlays.gentoo.org/(proj or dev)/(name)</pre>
345<pre caption="finally get it up there">git push origin master</pre>
346<p>Source: http://www.kernel.org/pub/software/scm/git/docs/tutorial.html</p>
347</body></section>
348
349<section>
350<title>Checking out the overlay with git</title>
351<body>
352<pre caption="clone it!">git clone git://git@git.overlays.gentoo.org/(proj or dev)/(name)/</pre>
317</body> 353</body>
318</section> 354</section>
319</chapter> 355</chapter>
320 356
321<chapter> 357<chapter>
326<body> 362<body>
327<p>One of the key features of o.g.o is that people who do not have write access 363<p>One of the key features of o.g.o is that people who do not have write access
328to the Gentoo Portage package tree can have write access to one or more 364to the Gentoo Portage package tree can have write access to one or more
329overlays. Several Gentoo projects have found that this is a great way to train 365overlays. Several Gentoo projects have found that this is a great way to train
330and evaluate potential Gentoo developers in a safe environment.</p> 366and evaluate potential Gentoo developers in a safe environment.</p>
331
332<p>At the moment, only the Overlays team can update the access control lists for
333overlays.gentoo.org. We will provide a web-based tool for managing the access
334control lists at a later date. But, for now, if you need a change made,
335please drop by #gentoo-overlays on IRC for assistance.</p>
336</body> 367</body>
337</section> 368</section>
338 369
339<section> 370<section>
340<title>Project Overlays: Giving Write Access To Team Members</title> 371<title>Project Overlays: Giving Write Access To Team Members</title>
474<ul> 505<ul>
475<li>A: You can pop into #gentoo-overlays on IRC, and talk to us there. The 506<li>A: You can pop into #gentoo-overlays on IRC, and talk to us there. The
476 current staff are mostly in European timezones.</li> 507 current staff are mostly in European timezones.</li>
477<li>A: You can send an email to overlays@gentoo.org. Someone will answer you as 508<li>A: You can send an email to overlays@gentoo.org. Someone will answer you as
478 soon as possible.</li> 509 soon as possible.</li>
479<li>A: You can contact Stuart Herbert (the project leader) directly, via his
480 email address: stuart@gentoo.org.</li>
481</ul> 510</ul>
482 511
483<p>Q: Why can't I edit the access control list directly?</p> 512<p>Q: Why can't I edit the access control list directly?</p>
484<ul> 513<ul>
485<li>A: The access control list currently lives in htpasswd / htgroup files used 514<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>
486 by Apache. Only o.g.o admin staff have ssh access into the o.g.o box.</li> 515<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>
487</ul> 516</ul>
488</body> 517</body>
489</section> 518</section>
490 519
491<section> 520<section>

Legend:
Removed from v.1.7  
changed lines
  Added in v.1.15

  ViewVC Help
Powered by ViewVC 1.1.20