/[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.22
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 3
4<guide link="/proj/en/overlays/devguide.xml"> 4<guide>
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> 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</author>
16<author title="Author">
17 <mail link="tampakrap">Theo Chatzimichos</mail>
18</author>
10 19
11<abstract>This guide helps developers understand how to use the Gentoo 20
12Overlays service.</abstract> 21<abstract>
22This guide helps developers and contributors understand how to
23use the Gentoo Overlays service.
24</abstract>
13 25
14<license/> 26<license/>
15 27
16<version>1.0</version> 28<version>2.4</version>
17<date>2006-07-29</date> 29<date>2010-05-01</date>
18 30
19<chapter> 31<chapter>
20<title>Introduction</title> 32<title>Introduction</title>
21 33
22<section> 34<section>
23<title>Audience</title> 35<title>Audience</title>
24<body> 36<body>
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>
26</body>
27</section>
28 37
29<section> 38<p>
30<title>What is overlays.gentoo.org?</title> 39This document has been written for Gentoo developers and users that want to
31<body> 40contribute. If you just want to start downloading and using overlays, please
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> 41see the <uri link="/proj/en/overlays/userguide.xml">Gentoo Overlays User Guide</uri>
42instead.
43</p>
44
33</body> 45</body>
34</section> 46</section>
35 47
36<section> 48<section>
37<title>Who Can Use overlays.gentoo.org?</title> 49<title>Who Can Use overlays.gentoo.org?</title>
38<body> 50<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>
40 51
41<p>Any Gentoo staff member or user (ie, anyone who doesn't have write access to 52<p>
42the main Portage package tree) can download and use the contents of any hosted 53Any Gentoo project, Gentoo developer, or Gentoo user can have their own overlay
54hosted on *.overlays.gentoo.org, with the RSS feed from the changelog included
55on <uri link="http://overlays.gentoo.org">the overlays.gentoo.org planet</uri>.
56</p>
57
58<p>
59Any User can download and use the contents of any hosted
43overlay. If you choose, you can also give users write access to your 60overlay. If you choose, you can also give users write access to your
44overlay.</p> 61overlay.
62</p>
63
45</body> 64</body>
46</section> 65</section>
47 66
48<section> 67<section>
49<title>What Does overlays.gentoo.org Give Me?</title> 68<title>What Does overlays.gentoo.org Give Me?</title>
50<body> 69<body>
70
71<p>
51<p>The overlays.gentoo.org service currently provides:</p> 72The *.overlays.gentoo.org service currently provides:
52<ul> 73</p>
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> 74
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>
56</ul> 75<ul>
76 <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</ul>
57 91
92<p>
58<p>... all hosted on secure, backed-up Gentoo infrastructure, administered by 93... 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> 94<uri link="/proj/en/infrastructure">the Gentoo Infrastructure team</uri>
60(wiki / VCS / ACLs).</p> 95(hardware / base OS) and <uri link="/proj/en/overlays">the Gentoo Overlays
96team</uri> (wiki / VCS / ACLs).
97</p>
61 98
99<p>
62<p>Each overlay has separate authentication lists for Trac and for Subversion. 100Each 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 101It'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> 102writing documentation) without giving them write access to Subversion.
103</p>
104
65</body> 105</body>
66</section> 106</section>
67 107
68<section> 108<section>
69<title>Why Should We Use overlays.gentoo.org?</title> 109<title>Why Should We Use overlays.gentoo.org?</title>
70<body> 110<body>
111
112<p>
71<p>You don't have to. You don't have to have an overlay at all, and if you do 113You don't have to. You don't have to have an overlay at all, and if you do
72have one, you are absolutely free to host your own overlay somewhere else. 114have one, you are absolutely free to host your own overlay somewhere else.
73You don't have to host an overlay on o.g.o for it to be considered 115You don't have to host an overlay on o.g.o for it to be considered "official".
74"official".</p> 116</p>
75 117
118<p>
76<p>The advantage of using overlays.gentoo.org is that we already have everything 119The advantage of using overlays.gentoo.org is that we already have everything
77setup for you. You don't need to admin your own server, or worry about 120setup for you. You don't need to admin your own server, or worry about
78software upgrades. We take care of all of that for you.</p> 121software upgrades. We take care of all of that for you.
122</p>
123
79</body> 124</body>
80</section> 125</section>
81 126
82<section> 127<section>
83<title>When Should We Not Use overlays.gentoo.org?</title> 128<title>When Should We Not Use overlays.gentoo.org?</title>
84<body> 129<body>
130
131<p>
85<p>The purpose of o.g.o is to help bridge the gap between developers and users. 132The purpose of o.g.o is to help bridge the gap between developers and users.
86Gentoo is a community-based distribution, and we believe that our users are 133Gentoo is a community-based distribution, and we believe that our users are
87just as important a part of that community as developers are.</p> 134just as important a part of that community as developers are.
135</p>
88 136
137<p>
89<p>All of the overlays hosted on o.g.o are there for all users to download and 138All of the overlays hosted on o.g.o are there for all users to download and
90use. It's for users to make their own decision about what software they 139use. It's for users to make their own decision about what software they
91install on their computers - and that includes choosing to use your overlay. 140install on their computers - and that includes choosing to use your overlay.
92Some users will make bad decisions, and end up breaking their computer. They 141Some users will make bad decisions, and end up breaking their computer. They
93may even end up blaming Gentoo as a result. That's okay; these people 142may even end up blaming Gentoo as a result. That's okay; these people
94probably go around blaming everyone but themselves for their own 143probably go around blaming everyone but themselves for their own
95mistakes anyway, and there's probably nothing you can do to change that. 144mistakes anyway, and there's probably nothing you can do to change that.
96But that still doesn't give any of us the right to choose for them.</p> 145But that still doesn't give any of us the right to choose for them.
146</p>
97 147
148<p>
98<p>Users are free (in fact, they are encouraged) to provide constructive 149Users are free (in fact, they are encouraged) to provide constructive
99feedback about anything to do with Gentoo - including all of the overlays 150feedback about anything to do with Gentoo - including all of the overlays
100hosted on o.g.o. That feedback can come via bugs.g.o, via email to your 151hosted on o.g.o. That feedback can come via bugs.g.o, via email to your
101project team or directly to you, via the forums, or via IRC. We're not 152project team or directly to you, via the forums, or via IRC. We're not
102talking about genuinely abusive users; we have no time for those, and no-one 153talking about genuinely abusive users; we have no time for those, and no-one
103expects you to have any time for them either.</p> 154expects you to have any time for them either.
155</p>
104 156
157<warn>
105<warn>If you're not happy with users using your overlay, and / or if you don't want 158If 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 159users bothering you about your overlay, then don't use o.g.o to host your
107overlay.</warn> 160overlay, or remove your overlay from the overlays list (repositories.xml).
161</warn>
108 162
109<p>The other thing we need to say is that o.g.o is for hosting overlays. You 163<p>
110can't use it to be $UPSTREAM for your packages. If that's the kind of hosting 164o.g.o used to have restrictions of not being the $UPSTREAM for packages.
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 165This restriction has been adjusted. We do offer hosting as the $UPSTREAM now,
166but only for packages that are Gentoo-specific or important to the running of
167Gentoo. Other hosting may be more suitable, some services in this vein are:
168<uri link="http://www.sourceforge.net/">SourceForge.net</uri>, <uri
169link="http://www.berlios.de">Berlios</uri>, Patrick's <uri
112Patrick's <uri link="http://www.gentooexperimental.org">GentooExperimental.org</uri>.</p> 170link="http://www.gentooexperimental.org">GentooExperimental.org</uri>, <uri
171link="http://www.github.com">GitHub</uri> or <uri link="http://www.gitorious.org">
172Gitorious</uri>.
173</p>
174
113</body> 175</body>
114</section> 176</section>
115</chapter> 177</chapter>
116 178
117<chapter> 179<chapter>
118<title>Requesting An Overlay</title> 180<title>Requesting An Overlay</title>
119 181
120<section> 182<section>
121<title>Introduction</title> 183<title>Introduction</title>
122<body> 184<body>
123<p>There are two types of overlay - "project" overlays, and "developer" 185<p>There are three types of overlays: "project" overlays, "developer"
124overlays. The only difference between them is responsibility and 186overlays and user overlays. The only difference between them is responsibility
125accountability.</p> 187and accountability.</p>
126 188
127<impo>Before requesting an overlay, please make sure that you have read our <uri link="/proj/en/overlays/policy.xml">Policy Document</uri>. It clearly sets out what's allowed and what is not, and what your responsibilities will be.</impo> 189<impo>
190Before 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
192out what's allowed and what is not, and what your responsibilities will be.
193</impo>
194
128</body> 195</body>
129</section> 196</section>
130 197
131<section> 198<section>
132<title>Project Overlays</title> 199<title>Project Overlays</title>
133<body> 200<body>
201
202<p>
134<p>"Project" overlays are overlays for official Gentoo projects. A good 203"Project" overlays are overlays for official Gentoo projects. An example is
135example is <uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.</p> 204<uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.
205</p>
136 206
207<p>
137<p>An official Gentoo project is a project that has a project page on 208An 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 209www.gentoo.org, and that has an elected lead. (This definition comes from the
139metastructure document</uri>, which is Gentoo's governing document). The project 210metastructure document). The project lead(s) are responsible for the project
140lead(s) are responsible for the project overlay, including its contents, and 211overlay, including its contents, and any problems it causes other Gentoo projects
141any problems it causes other Gentoo projects and developers.</p> 212and developers.
213</p>
142 214
215<p>
143<p>To request a project overlay, the project's lead just needs to pop into 216To 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 217#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, 218prefers, 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 219including granting write access to all the members of your project (as listed
147on your project page).</p> 220on your project page).
221</p>
148 222
149<p>We will:</p> 223<p>
224To request a Git project overlay, just visit the <uri
225link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
226setup instructions, emailing the completed template as directed.
227</p>
228
229<p>
230For an SVN request, we will:
231</p>
232
150<ul> 233<ul>
234 <li>
151<li>create your overlay (trac site + svn)</li> 235 create your overlay (trac site + svn)
236 </li>
237 <li>
152<li>add your overlay's RSS feed to the o.g.o homepage</li> 238 add your overlay's RSS feed to the o.g.o homepage
239 </li>
240 <li>
153<li>create an o.g.o account for you if you don't already have one</li> 241 create an o.g.o account for you if you don't already have one
242 </li>
243 <li>
154<li>give you write access to your overlay's Trac wiki and Subversion 244 give you write access to your overlay's Trac wiki and Subversion
155repository</li> 245 repository
246 </li>
247 <li>
156<li>give write access to all project members who already have an o.g.o 248 give write access to all project members who already have an o.g.o
157account</li> 249 account
158<li>contact all of the other project members, and sort out their access</li> 250 </li>
251</ul>
252
253<p>
254For an Git request, we will:
255</p>
256
159</ul> 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</ul>
274
160</body> 275</body>
161</section> 276</section>
162 277
163<section> 278<section>
164<title>Developer Overlays</title> 279<title>Developer Overlays</title>
165<body> 280<body>
166 281
282<p>
167<p>"Developer" overlays are overlays owned by individual Gentoo developers. One 283"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> 284example is <uri link="http://overlays.gentoo.org/dev/beandog">beandog's
285overlay</uri>.
286</p>
169 287
288<p>
170<p>If you have an @gentoo.org email address, and you've passed the ebuild quiz, 289If 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> 290then you can have your own developer overlay on o.g.o.
291</p>
172 292
293<p>
173<p>To request a developer overlay, just pop into #gentoo-overlays on IRC and ask 294To 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 295and ask for an overlay to be created for you. Or, if you prefer, drop an email
175overlays@gentoo.org.</p> 296to overlays@gentoo.org.
297</p>
176 298
177<p>We will:</p> 299<p>
300To request a Git developer overlay, just visit the <uri
301link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
302setup instructions, emailing the completed template as directed.
303</p>
304
305<p>
306For an SVN request, we will:
307</p>
308
178<ul> 309<ul>
310 <li>
179<li>create your overlay (trac site + svn)</li> 311 create your overlay (trac site + svn)
312 </li>
313 <li>
180<li>add your overlay's RSS feed to the o.g.o homepage</li> 314 add your overlay's RSS feed to the o.g.o homepage
315 </li>
316 <li>
181<li>create an o.g.o account for you if you don't have one already</li> 317 create an o.g.o account for you if you don't have one already
318 </li>
319 <li>
182<li>give you write access to your overlay's Trac wiki and Subversion 320 give you write access to your overlay's Trac wiki and Subversion
183repository</li> 321 repository
322 </li>
323</ul>
324
325<p>
326For an Git request, we will:
327</p>
328
184</ul> 329<ul>
330 <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</ul>
343
185</body> 344</body>
186</section> 345</section>
187 346
188<section> 347<section>
189<title>A Word About Accounts</title> 348<title>A Word About Accounts</title>
190<body> 349<body>
350
351<p>
191<p>Because o.g.o is designed to support a blend of both Gentoo developers and 352Because 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. 353Gentoo 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 354</p>
194htgroup files.</p>
195 355
196<impo>You do *not* have SSH access to o.g.o.</impo> 356<impo>You do *not* have SSH access to o.g.o.</impo>
357
197</body> 358</body>
198</section> 359</section>
199</chapter> 360</chapter>
200 361
201<chapter> 362<chapter>
202<title>Working With Your Overlay</title> 363<title>Working With Your Overlay</title>
203 364
204<section> 365<section>
205<title>Introduction</title> 366<title>Introduction</title>
206<body> 367<body>
368
369<p>
207<p>You can access your overlay as soon as it has been created. Project and 370You can access your overlay as soon as it has been created. Project and
208developer overlays have different URLs, so that everyone can tell one from the 371developer overlays have different URLs, so that everyone can tell one from the
209other, but otherwise they are identical in every way.</p> 372other, but otherwise they are identical in every way.
373</p>
210 374
375<p>
211<p>There are *no* read restrictions on overlays or wikis. Everyone has full 376There are *no* read restrictions on overlays or wikis. Everyone has full
212read access to all overlays and wikis. If you need a 'secret' overlay of some 377read access to all overlays and wikis. If you need a 'secret' overlay of some
213kind, then o.g.o is not for you.</p> 378kind, then o.g.o is not for you.
379</p>
380
214</body> 381</body>
215</section> 382</section>
216 383
217<section> 384<section>
218<title>Accessing Project Overlays</title> 385<title>Accessing Project Overlays</title>
219<body> 386<body>
387
388<p>
220<p>If your project overlay is called 'foo', your Trac wiki site will be 389If your project overlay is called 'foo', your Trac wiki site will be
221here: http://overlays.gentoo.org/proj/foo/</p> 390here: http://overlays.gentoo.org/proj/foo/
391</p>
222 392
393<p>
223<p>To checkout your Subversion repository, use:</p> 394To checkout your Subversion repository, use:
224<pre caption="Checkout your project overlay">svn co http://overlays.gentoo.org/svn/proj/foo/</pre> 395</p>
225 396
226<p>We maintain <uri link="http://overlays.gentoo.org/proj/">a full list of project overlays hosted on overlays.gentoo.org</uri>.</p> 397<pre caption="Checkout your project overlay">
398svn co https://overlays.gentoo.org/svn/proj/foo/</pre>
399
400<p>
401While you may perform read-only actions via unsecure HTTP, you must perform
402all 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">
406svn sw --relocate http://overlays.gentoo.org/svn/proj/foo/
407https://overlays.gentoo.org/svn/proj/foo/</pre>
408
409<p>
410We maintain <uri link="http://overlays.gentoo.org/proj/">a full list of
411project overlays hosted on overlays.gentoo.org</uri>.
412</p>
413
227</body> 414</body>
228</section> 415</section>
229 416
230<section> 417<section>
231<title>Accessing Developer Overlays</title> 418<title>Accessing Developer Overlays</title>
232<body> 419<body>
420
421<p>
233<p>If your Gentoo email address is 'foo@gentoo.org', your Trac wiki site will be 422If your Gentoo email address is 'foo@gentoo.org', your Trac wiki site will be
234here: http://overlays.gentoo.org/dev/foo/</p> 423here: http://overlays.gentoo.org/dev/foo/
424</p>
235 425
426<p>
236<p>To checkout your Subversion repository, use:</p> 427To checkout your Subversion repository, use:
237<pre caption="Checkout your developer overlay">svn co http://overlays.gentoo.org/svn/dev/foo/</pre> 428</p>
238 429
239<p>We maintain <uri link="http://overlays.gentoo.org/dev/">a full list of developer overlays hosted on overlays.gentoo.org</uri>.</p> 430<pre caption="Checkout your developer overlay">svn co
431https://overlays.gentoo.org/svn/dev/foo/</pre>
432
433<p>
434While you may perform read-only actions via unsecure HTTP, you must perform
435all 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>
442We maintain <uri link="http://overlays.gentoo.org/dev/">a full list of
443developer overlays hosted on overlays.gentoo.org</uri>.
444</p>
445
240</body> 446</body>
241</section> 447</section>
242 448
243<section> 449<section>
244<title>Getting Started With Trac</title> 450<title>Getting Started With Trac</title>
245<body> 451<body>
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 452
453<p>
454Your overlay comes with <uri link="http://trac.edgewall.com">Trac</uri>.
455Trac is a wiki, a subversion repository browser, and a bug tracking system that's
247very popular with open source developers.</p> 456very popular with open source developers.
457</p>
248 458
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> 459<p>
460We have disabled the bug tracking system in Trac. Use <uri
461link="http://bugs.gentoo.org">Gentoo's bugzilla</uri> for bug tracking your
462overlay.
463</p>
250 464
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> 465<p>
252 466Your overlay's RSS feed - the one that is shown on <uri
253<p>We have installed several Trac plugins, which we hope will make your wiki even 467link="http://overlays.gentoo.org">the o.g.o homepage</uri> - comes from Trac's
254more useful to you. If you come across any additional plugins that you'd like 468Timeline page or GitWeb's summary.
255to see installed, please let us know, and we'll take a look at them.</p> 469</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 470
271</body> 471</body>
272</section> 472</section>
273 473
274<section> 474<section>
275<title>Getting Started With Subversion</title> 475<title>Getting Started With Subversion</title>
276<body> 476<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>
278 477
478<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
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> 480<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 481
281<p>Here are some basic commands to get you started.</p> 482<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> 483<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> 484<pre caption="Seeing which files need committing">svn status</pre>
284<pre caption="Adding files to your overlay">svn add my.ebuild</pre> 485<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> 486<pre caption="Committing your changes">svn commit -m 'My changelog entry'</pre>
286 487
287</body> 488</body>
291<title>Layman</title> 492<title>Layman</title>
292<body> 493<body>
293<p>We are telling users to use layman to download and manage your overlay. 494<p>We are telling users to use layman to download and manage your overlay.
294layman 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> 495layman 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>
295 496
296<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> 497<p>
498To get started with using layman, see <uri
499link="http://layman.sourceforge.net/">the homepage documentation</uri>, the <uri
500link="http://www.gentoo.org/news/en/gwn/20060522-newsletter.xml">Gentoo Weekly
501News for 22nd May</uri> or read <c>man layman</c>.
502</p>
297</body> 503</body>
298</section> 504</section>
299 505
300<section> 506<section>
301<title>Auto-Sync From Portage</title> 507<title>Auto-Sync From Portage</title>
309<p>You need to make sure that the changes made in Portage aren't lost the next 515<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> 516time you copy your packages from your overlay back into Portage.</p>
311 517
312<p>The PHP team have solved this problem by automatically copying their packages 518<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 519from 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 520can 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 521
522</body>
523</section>
524</chapter>
525
526<chapter>
527<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
535git add .
536git commit -m "populate overlay"</pre>
537<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<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<pre caption="clone it!">git clone git://git@git.overlays.gentoo.org/(proj or dev)/(name)/</pre>
317</body> 547</body>
318</section> 548</section>
319</chapter> 549</chapter>
320 550
321<chapter> 551<chapter>
326<body> 556<body>
327<p>One of the key features of o.g.o is that people who do not have write access 557<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 558to 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 559overlays. Several Gentoo projects have found that this is a great way to train
330and evaluate potential Gentoo developers in a safe environment.</p> 560and 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> 561</body>
337</section> 562</section>
338 563
339<section> 564<section>
340<title>Project Overlays: Giving Write Access To Team Members</title> 565<title>Project Overlays: Giving Write Access To Team Members</title>
422<body> 647<body>
423<p>Everyone has full read access to every overlay. We recommend that you 648<p>Everyone has full read access to every overlay. We recommend that you
424use</p> 649use</p>
425<pre caption="Install layman"> 650<pre caption="Install layman">
426 emerge layman 651 emerge layman
427 echo 'source /usr/portage/local/layman/layman.conf' &gt;&gt; /etc/make.conf 652 echo 'source /var/lib/layman/layman.conf' &gt;&gt; /etc/make.conf
428</pre> 653</pre>
429 654
430<note> 655<note>
431Layman will create "/usr/portage/local/layman/make.conf" once you add 656Layman will create "/var/lib/layman/make.conf" once you add
432your first overlay. But if you do not plan to install an overlay 657your first overlay. But if you do not plan to install an overlay
433immediately you should ensure that this file actually exists and 658immediately you should ensure that this file actually exists and
434contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will 659contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will
435complain. You can run "echo PORTDIR_OVERLAY=\"\" > 660complain. You can run "echo PORTDIR_OVERLAY='' >
436/usr/portage/local/layman/make.conf" in order to have the file created 661/var/lib/layman/make.conf" in order to have the file created
437correctly. 662correctly.
438</note> 663</note>
439 664
440<p>After that, to view the list of overlays, use</p> 665<p>After that, to view the list of overlays, use</p>
441 666
474<ul> 699<ul>
475<li>A: You can pop into #gentoo-overlays on IRC, and talk to us there. The 700<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> 701 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 702<li>A: You can send an email to overlays@gentoo.org. Someone will answer you as
478 soon as possible.</li> 703 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> 704</ul>
482 705
483<p>Q: Why can't I edit the access control list directly?</p> 706<p>Q: Why can't I edit the access control list directly?</p>
484<ul> 707<ul>
485<li>A: The access control list currently lives in htpasswd / htgroup files used 708<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> 709<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> 710</ul>
488</body> 711</body>
489</section> 712</section>
490 713
491<section> 714<section>

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

  ViewVC Help
Powered by ViewVC 1.1.20