/[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.14
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.1</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
104 112
105<warn>If you're not happy with users using your overlay, and / or if you don't want 113<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 114users bothering you about your overlay, then don't use o.g.o to host your
107overlay.</warn> 115overlay.</warn>
108 116
109<p>The other thing we need to say is that o.g.o is for hosting overlays. You 117<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 118This 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 119but only for packages that are Gentoo-specific or important to the running of
120Gentoo. Other hosting may be more suitable, some services in this vein are:
121<uri link="http://www.sourceforge.net/">SourceForge.net</uri>, <uri
122link="http://www.berlios.de">Berlios</uri>, or Patrick's <uri
112Patrick's <uri link="http://www.gentooexperimental.org">GentooExperimental.org</uri>.</p> 123link="http://www.gentooexperimental.org">GentooExperimental.org</uri>.</p>
113</body> 124</body>
114</section> 125</section>
115</chapter> 126</chapter>
116 127
117<chapter> 128<chapter>
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 149www.gentoo.org, and that has an elected lead. (This definition comes from <uri link="http://www.gentoo.org/proj/en/glep/glep-0039.html">the
139metastructure document</uri>, which is Gentoo's governing document). The project 150metastructure document</uri>, which is Gentoo's governing document). The project
140lead(s) are responsible for the project overlay, including its contents, and 151lead(s) are responsible for the project overlay, including its contents, and
141any problems it causes other Gentoo projects and developers.</p> 152any problems it causes other Gentoo projects and developers.</p>
142 153
143<p>To request a project overlay, the project's lead just needs to pop into 154<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 155#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, 156prefers, 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 157including granting write access to all the members of your project (as listed
147on your project page).</p> 158on your project page).</p>
148 159
149<p>We will:</p> 160<p>To request a Git project overlay, just visit the <uri
161link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
162setup instructions, emailing the completed template as directed.</p>
163
164<p>For an SVN request, we will:</p>
150<ul> 165<ul>
151<li>create your overlay (trac site + svn)</li> 166<li>create your overlay (trac site + svn)</li>
152<li>add your overlay's RSS feed to the o.g.o homepage</li> 167<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> 168<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 169<li>give you write access to your overlay's Trac wiki and Subversion
155repository</li> 170repository</li>
156<li>give write access to all project members who already have an o.g.o 171<li>give write access to all project members who already have an o.g.o
157account</li> 172account</li>
158<li>contact all of the other project members, and sort out their access</li> 173<li>contact all of the other project members, and sort out their access</li>
159</ul> 174</ul>
175
176<p>For an Git request, we will:</p>
177<ul>
178<li>create your overlay (git, gitweb, no trac)</li>
179<li>add your overlay's RSS feed to the o.g.o homepage</li>
180<li>create an git.o.g.o account for you if you don't already have one</li>
181<li>give you write access to your overlays Git repository</li>
182<li>give write access to all project members who already have an o.g.o account</li>
183<li>contact all of the other project members, and sort out their access</li>
184</ul>
185
186
160</body> 187</body>
161</section> 188</section>
162 189
163<section> 190<section>
164<title>Developer Overlays</title> 191<title>Developer Overlays</title>
168example is <uri link="http://overlays.gentoo.org/dev/tcort">tcort's overlay</uri>.</p> 195example is <uri link="http://overlays.gentoo.org/dev/tcort">tcort's overlay</uri>.</p>
169 196
170<p>If you have an @gentoo.org email address, and you've passed the ebuild quiz, 197<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> 198then you can have your own developer overlay on o.g.o.</p>
172 199
173<p>To request a developer overlay, just pop into #gentoo-overlays on IRC and ask 200<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 201and ask for an overlay to be created for you. Or, if you prefer, drop an email
175overlays@gentoo.org.</p> 202to overlays@gentoo.org.</p>
176 203
177<p>We will:</p> 204<p>To request a Git developer overlay, just visit the <uri
205link="http://git.overlays.gentoo.org">git.overlays</uri> site, and follow the
206setup instructions, emailing the completed template as directed.</p>
207
208<p>For an SVN request, we will:</p>
178<ul> 209<ul>
179<li>create your overlay (trac site + svn)</li> 210<li>create your overlay (trac site + svn)</li>
180<li>add your overlay's RSS feed to the o.g.o homepage</li> 211<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> 212<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 213<li>give you write access to your overlay's Trac wiki and Subversion
183repository</li> 214repository</li>
184</ul> 215</ul>
216
217<p>For an Git request, we will:</p>
218<ul>
219<li>create your overlay (git, gitweb, no trac)</li>
220<li>add your overlay's RSS feed to the o.g.o homepage</li>
221<li>create an git.o.g.o account for you if you don't already have one</li>
222<li>give you write access to your overlays Git repository</li>
223</ul>
185</body> 224</body>
186</section> 225</section>
187 226
188<section> 227<section>
189<title>A Word About Accounts</title> 228<title>A Word About Accounts</title>
219<body> 258<body>
220<p>If your project overlay is called 'foo', your Trac wiki site will be 259<p>If your project overlay is called 'foo', your Trac wiki site will be
221here: http://overlays.gentoo.org/proj/foo/</p> 260here: http://overlays.gentoo.org/proj/foo/</p>
222 261
223<p>To checkout your Subversion repository, use:</p> 262<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> 263<pre caption="Checkout your project overlay">svn co https://overlays.gentoo.org/svn/proj/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 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 268
226<p>We maintain <uri link="http://overlays.gentoo.org/proj/">a full list of project overlays hosted on overlays.gentoo.org</uri>.</p> 269<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> 270</body>
228</section> 271</section>
229 272
232<body> 275<body>
233<p>If your Gentoo email address is 'foo@gentoo.org', your Trac wiki site will be 276<p>If your Gentoo email address is 'foo@gentoo.org', your Trac wiki site will be
234here: http://overlays.gentoo.org/dev/foo/</p> 277here: http://overlays.gentoo.org/dev/foo/</p>
235 278
236<p>To checkout your Subversion repository, use:</p> 279<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> 280<pre caption="Checkout your developer overlay">svn co https://overlays.gentoo.org/svn/dev/foo/</pre>
281
282<p>While you may perform read-only actions via unsecure HTTP, you must perform
283all commits via HTTPS. If you need to switch between modes, use:</p>
284<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 285
239<p>We maintain <uri link="http://overlays.gentoo.org/dev/">a full list of developer overlays hosted on overlays.gentoo.org</uri>.</p> 286<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> 287</body>
241</section> 288</section>
242 289
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> 324<p>Your overlay comes with <uri link="http://subversion.tigris.org">Subversion</uri>, a modern alternative to CVS. The advantages of Subversion over CVS include real versioning of directories, full changeset support, and it's much easier to do branching if you need to. The main disadvantage of Subversion is that it is slower than CVS, and that a local Subversion checkout requires more disk space.</p>
278 325
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> 326<p>If you have never used Subversion before, the <uri link="http://svnbook.red-bean.com/">online book</uri> is an excellent way to learn Subversion. You can buy it in dead-tree format too if you prefer.</p>
280 327
281<p>Here are some basic commands to get you started.</p> 328<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> 329<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> 330<pre caption="Seeing which files need committing">svn status</pre>
284<pre caption="Adding files to your overlay">svn add my.ebuild</pre> 331<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> 332<pre caption="Committing your changes">svn commit -m 'My changelog entry'</pre>
286 333
287</body> 334</body>
309<p>You need to make sure that the changes made in Portage aren't lost the next 356<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> 357time you copy your packages from your overlay back into Portage.</p>
311 358
312<p>The PHP team have solved this problem by automatically copying their packages 359<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 360from 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 361can 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 362
363</body>
364</section>
365</chapter>
366
367<chapter>
368<title>Using git on overlays</title>
369
370<section>
371<title>Initializing your overlay</title>
372<body>
373<p>Before uploading you need to locally create a git repository and add all items:</p>
374<pre caption="go to your overlay">cd ~/my-overlay</pre>
375<pre caption="create a new git repo">git init
376git add .
377git commit -m "populate overlay"</pre>
378<p>Note that this commit was only locally, now we get the server into the game.</p>
379<pre caption="tell git the url">git remote add origin git+ssh://git@git.overlays.gentoo.org/(proj or dev)/(name)</pre>
380<pre caption="finally get it up there">git push origin master</pre>
381<p>Source: http://www.kernel.org/pub/software/scm/git/docs/tutorial.html</p>
382</body></section>
383
384<section>
385<title>Checking out the overlay with git</title>
386<body>
387<pre caption="clone it!">git clone git://git@git.overlays.gentoo.org/(proj or dev)/(name)/</pre>
317</body> 388</body>
318</section> 389</section>
319</chapter> 390</chapter>
320 391
321<chapter> 392<chapter>
474<ul> 545<ul>
475<li>A: You can pop into #gentoo-overlays on IRC, and talk to us there. The 546<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> 547 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 548<li>A: You can send an email to overlays@gentoo.org. Someone will answer you as
478 soon as possible.</li> 549 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> 550</ul>
482 551
483<p>Q: Why can't I edit the access control list directly?</p> 552<p>Q: Why can't I edit the access control list directly?</p>
484<ul> 553<ul>
485<li>A: The access control list currently lives in htpasswd / htgroup files used 554<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> 555 by Apache. Only o.g.o admin staff have ssh access into the o.g.o box.</li>
556<li>A: (Git) The access control list currently lives in the gitosis-admin repository,
557 which is writable only by the o.g.o staff.</li>
487</ul> 558</ul>
488</body> 559</body>
489</section> 560</section>
490 561
491<section> 562<section>

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

  ViewVC Help
Powered by ViewVC 1.1.20