/[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.12
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.0</version>
17<date>2006-07-29</date> 23<date>2008-10-12</date>
18 24
19<chapter> 25<chapter>
20<title>Introduction</title> 26<title>Introduction</title>
21 27
22<section> 28<section>
49<title>What Does overlays.gentoo.org Give Me?</title> 55<title>What Does overlays.gentoo.org Give Me?</title>
50<body> 56<body>
51<p>The overlays.gentoo.org service currently provides:</p> 57<p>The overlays.gentoo.org service currently provides:</p>
52<ul> 58<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> 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>
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> 60<li><uri link="http://subversion.tigris.org">Subversion</uri> - a centralised version control system</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> 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>
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>
56</ul> 64</ul>
57 65
58<p>... all hosted on secure, backed-up Gentoo infrastructure, administered by 66<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> 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>
60(wiki / VCS / ACLs).</p> 68(wiki / VCS / ACLs).</p>
61 69
62<p>Each overlay has separate authentication lists for Trac and for Subversion. 70<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 71It'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> 72writing documentation) without giving them write access to Subversion.</p>
65</body> 73</body>
66</section> 74</section>
67 75
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 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
139metastructure document</uri>, which is Gentoo's governing document). The project 147metastructure document</uri>, which is Gentoo's governing document). The project
140lead(s) are responsible for the project overlay, including its contents, and 148lead(s) are responsible for the project overlay, including its contents, and
141any problems it causes other Gentoo projects and developers.</p> 149any problems it causes other Gentoo projects and developers.</p>
142 150
143<p>To request a project overlay, the project's lead just needs to pop into 151<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 152#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, 153prefers, 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 154including granting write access to all the members of your project (as listed
147on your project page).</p> 155on your project page).</p>
148 156
149<p>We will:</p> 157<p>To request a Git project overlay, just visit the <uri
158link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
159setup instructions, emailing the completed template as directed.</p>
160
161<p>For an SVN request, we will:</p>
150<ul> 162<ul>
151<li>create your overlay (trac site + svn)</li> 163<li>create your overlay (trac site + svn)</li>
152<li>add your overlay's RSS feed to the o.g.o homepage</li> 164<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> 165<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 166<li>give you write access to your overlay's Trac wiki and Subversion
155repository</li> 167repository</li>
156<li>give write access to all project members who already have an o.g.o 168<li>give write access to all project members who already have an o.g.o
157account</li> 169account</li>
158<li>contact all of the other project members, and sort out their access</li> 170<li>contact all of the other project members, and sort out their access</li>
159</ul> 171</ul>
172
173<p>For an Git request, we will:</p>
174<ul>
175<li>create your overlay (git, gitweb, no trac)</li>
176<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>
178<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>
180<li>contact all of the other project members, and sort out their access</li>
181</ul>
182
183
160</body> 184</body>
161</section> 185</section>
162 186
163<section> 187<section>
164<title>Developer Overlays</title> 188<title>Developer Overlays</title>
168example is <uri link="http://overlays.gentoo.org/dev/tcort">tcort's overlay</uri>.</p> 192example is <uri link="http://overlays.gentoo.org/dev/tcort">tcort's overlay</uri>.</p>
169 193
170<p>If you have an @gentoo.org email address, and you've passed the ebuild quiz, 194<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> 195then you can have your own developer overlay on o.g.o.</p>
172 196
173<p>To request a developer overlay, just pop into #gentoo-overlays on IRC and ask 197<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 198and ask for an overlay to be created for you. Or, if you prefer, drop an email
175overlays@gentoo.org.</p> 199to overlays@gentoo.org.</p>
176 200
177<p>We will:</p> 201<p>To request a Git developer overlay, just visit the <uri
202link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
203setup instructions, emailing the completed template as directed.</p>
204
205<p>For an SVN request, we will:</p>
178<ul> 206<ul>
179<li>create your overlay (trac site + svn)</li> 207<li>create your overlay (trac site + svn)</li>
180<li>add your overlay's RSS feed to the o.g.o homepage</li> 208<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> 209<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 210<li>give you write access to your overlay's Trac wiki and Subversion
183repository</li> 211repository</li>
184</ul> 212</ul>
213
214<p>For an Git request, we will:</p>
215<ul>
216<li>create your overlay (git, gitweb, no trac)</li>
217<li>add your overlay's RSS feed to the o.g.o homepage</li>
218<li>create an git.o.g.o account for you if you don't already have one</li>
219<li>give you write access to your overlays Git repository</li>
220</ul>
185</body> 221</body>
186</section> 222</section>
187 223
188<section> 224<section>
189<title>A Word About Accounts</title> 225<title>A Word About Accounts</title>
219<body> 255<body>
220<p>If your project overlay is called 'foo', your Trac wiki site will be 256<p>If your project overlay is called 'foo', your Trac wiki site will be
221here: http://overlays.gentoo.org/proj/foo/</p> 257here: http://overlays.gentoo.org/proj/foo/</p>
222 258
223<p>To checkout your Subversion repository, use:</p> 259<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> 260<pre caption="Checkout your project overlay">svn co https://overlays.gentoo.org/svn/proj/foo/</pre>
261
262<p>While you may perform read-only actions via unsecure HTTP, you must perform
263all commits via HTTPS. If you need to switch between modes, use:</p>
264<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 265
226<p>We maintain <uri link="http://overlays.gentoo.org/proj/">a full list of project overlays hosted on overlays.gentoo.org</uri>.</p> 266<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> 267</body>
228</section> 268</section>
229 269
232<body> 272<body>
233<p>If your Gentoo email address is 'foo@gentoo.org', your Trac wiki site will be 273<p>If your Gentoo email address is 'foo@gentoo.org', your Trac wiki site will be
234here: http://overlays.gentoo.org/dev/foo/</p> 274here: http://overlays.gentoo.org/dev/foo/</p>
235 275
236<p>To checkout your Subversion repository, use:</p> 276<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> 277<pre caption="Checkout your developer overlay">svn co https://overlays.gentoo.org/svn/dev/foo/</pre>
278
279<p>While you may perform read-only actions via unsecure HTTP, you must perform
280all commits via HTTPS. If you need to switch between modes, use:</p>
281<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 282
239<p>We maintain <uri link="http://overlays.gentoo.org/dev/">a full list of developer overlays hosted on overlays.gentoo.org</uri>.</p> 283<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> 284</body>
241</section> 285</section>
242 286
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> 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>
278 322
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> 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>
280 324
281<p>Here are some basic commands to get you started.</p> 325<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> 326<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> 327<pre caption="Seeing which files need committing">svn status</pre>
284<pre caption="Adding files to your overlay">svn add my.ebuild</pre> 328<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> 329<pre caption="Committing your changes">svn commit -m 'My changelog entry'</pre>
286 330
287</body> 331</body>
309<p>You need to make sure that the changes made in Portage aren't lost the next 353<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> 354time you copy your packages from your overlay back into Portage.</p>
311 355
312<p>The PHP team have solved this problem by automatically copying their packages 356<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 357from 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 358can 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 359
360</body>
361</section>
362</chapter>
363
364<chapter>
365<title>Using git on overlays</title>
366
367<section>
368<title>Initializing your overlay</title>
369<body>
370<p>Before uploading you need to locally create a git repository and add all items:</p>
371<pre caption="go to your overlay">cd ~/my-overlay</pre>
372<pre caption="create a new git repo">git init
373git add .
374git commit -m "populate overlay"</pre>
375<p>Note that this commit was only locally, now we get the server into the game.</p>
376<pre caption="tell git the url">git remote add origin git+ssh://git@git.overlays.gentoo.org/(proj or dev)/(name)</pre>
377<pre caption="finally get it up there">git push origin master</pre>
378<p>Source: http://www.kernel.org/pub/software/scm/git/docs/tutorial.html</p>
379</body></section>
380
381<section>
382<title>Checking out the overlay with git</title>
383<body>
384<pre caption="clone it!">git clone git://git@git.overlays.gentoo.org/(proj or dev)/(name)/</pre>
317</body> 385</body>
318</section> 386</section>
319</chapter> 387</chapter>
320 388
321<chapter> 389<chapter>
474<ul> 542<ul>
475<li>A: You can pop into #gentoo-overlays on IRC, and talk to us there. The 543<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> 544 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 545<li>A: You can send an email to overlays@gentoo.org. Someone will answer you as
478 soon as possible.</li> 546 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> 547</ul>
482 548
483<p>Q: Why can't I edit the access control list directly?</p> 549<p>Q: Why can't I edit the access control list directly?</p>
484<ul> 550<ul>
485<li>A: The access control list currently lives in htpasswd / htgroup files used 551<li>A: (SVN) The access control list currently lives in htpasswd / htgroup files used
486 by Apache. Only o.g.o admin staff have ssh access into 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,
554 which is writable only by the o.g.o staff.</li>
487</ul> 555</ul>
488</body> 556</body>
489</section> 557</section>
490 558
491<section> 559<section>

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

  ViewVC Help
Powered by ViewVC 1.1.20