| 1 |
jokey 08/10/30 19:35:21 |
| 2 |
|
| 3 |
Modified: userguide.xml devguide.xml |
| 4 |
Log: |
| 5 |
Fix up Guides |
| 6 |
|
| 7 |
Revision Changes Path |
| 8 |
1.5 xml/htdocs/proj/en/overlays/userguide.xml |
| 9 |
|
| 10 |
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/overlays/userguide.xml?rev=1.5&view=markup |
| 11 |
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/overlays/userguide.xml?rev=1.5&content-type=text/plain |
| 12 |
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/overlays/userguide.xml?r1=1.4&r2=1.5 |
| 13 |
|
| 14 |
Index: userguide.xml |
| 15 |
=================================================================== |
| 16 |
RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/overlays/userguide.xml,v |
| 17 |
retrieving revision 1.4 |
| 18 |
retrieving revision 1.5 |
| 19 |
diff -u -r1.4 -r1.5 |
| 20 |
--- userguide.xml 11 Nov 2006 22:21:04 -0000 1.4 |
| 21 |
+++ userguide.xml 30 Oct 2008 19:35:20 -0000 1.5 |
| 22 |
@@ -5,15 +5,19 @@ |
| 23 |
<title>Gentoo Overlays: Users' Guide</title> |
| 24 |
|
| 25 |
<author title="Author"> |
| 26 |
- <mail link="stuart@g.o">Stuart Herbert</mail> |
| 27 |
+ <mail link="stuart">Stuart Herbert</mail> |
| 28 |
+</author> |
| 29 |
+ |
| 30 |
+<author title="Author"> |
| 31 |
+ <mail link="jokey">Markus Ullmann</mail> |
| 32 |
</author> |
| 33 |
|
| 34 |
<abstract>This guide helps users understand how to use the Gentoo Overlays service</abstract> |
| 35 |
|
| 36 |
<license/> |
| 37 |
|
| 38 |
-<version>1.0</version> |
| 39 |
-<date>2006-07-30</date> |
| 40 |
+<version>1.1</version> |
| 41 |
+<date>2008-10-30</date> |
| 42 |
|
| 43 |
<chapter> |
| 44 |
<title>Introduction</title> |
| 45 |
@@ -29,7 +33,7 @@ |
| 46 |
<section> |
| 47 |
<title>What Are Overlays?</title> |
| 48 |
<body> |
| 49 |
-<p>"Overlays" are package trees for Portage. They contain additional ebuilds for Gentoo. They are maintained by Gentoo developers, but are distributed separately from the main Portage tree.</p> |
| 50 |
+<p>"Overlays" are package trees for Portage. They contain additional ebuilds for Gentoo. They are maintained by Gentoo developers and projects but distributed separately from the main Portage tree.</p> |
| 51 |
</body> |
| 52 |
</section> |
| 53 |
|
| 54 |
@@ -47,12 +51,11 @@ |
| 55 |
</section> |
| 56 |
|
| 57 |
<section> |
| 58 |
-<title>What Is overlays.gentoo.org?</title> |
| 59 |
+<title>What is the Gentoo Overlays Project?</title> |
| 60 |
<body> |
| 61 |
-<p><uri link="http://overlays.gentoo.org">overlays.gentoo.org</uri> provides social workspaces to allow Gentoo projects, |
| 62 |
+<p>Gentoo Overlays provide social workspaces to allow Gentoo projects, |
| 63 |
developers and users to collaborate together on tomorrow's Gentoo packages. |
| 64 |
-We do this by host overlays for Gentoo projects, and overlays for Gentoo |
| 65 |
-developers.</p> |
| 66 |
+We do this by hosting overlays for Gentoo projects and developers.</p> |
| 67 |
</body> |
| 68 |
</section> |
| 69 |
|
| 70 |
@@ -79,10 +82,10 @@ |
| 71 |
<p>To install layman, follow these steps:</p> |
| 72 |
<pre caption="Installing layman"> |
| 73 |
<i>emerge layman</i> |
| 74 |
-<i>echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf</i> |
| 75 |
+<i>echo "source /usr/local/portage/layman/make.conf" >> /etc/make.conf</i> |
| 76 |
</pre> |
| 77 |
<note> |
| 78 |
-Layman will create "/usr/portage/local/layman/make.conf" once you add |
| 79 |
+Layman will create "/usr/local/portage/layman/make.conf" once you add |
| 80 |
your first overlay. But if you do not plan to install an overlay |
| 81 |
immediately you should ensure that this file actually exists and |
| 82 |
contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will |
| 83 |
@@ -94,7 +97,7 @@ |
| 84 |
</section> |
| 85 |
|
| 86 |
<section> |
| 87 |
-<title>Listing The Overlays Available</title> |
| 88 |
+<title>Listing The Available Overlays</title> |
| 89 |
<body> |
| 90 |
<p>To see the list of overlays available, run:</p> |
| 91 |
<pre caption="Listing the available overlays">layman -L</pre> |
| 92 |
@@ -137,7 +140,7 @@ |
| 93 |
<body> |
| 94 |
<p>To keep your installed overlays up to date, run:</p> |
| 95 |
<pre caption="Updating All Installed Overlays"> |
| 96 |
-layman --sync ALL |
| 97 |
+layman -S |
| 98 |
</pre> |
| 99 |
<p>Please don't run this more than once a day, or you'll put too much strain on |
| 100 |
Gentoo's infrastructure.</p> |
| 101 |
@@ -151,13 +154,12 @@ |
| 102 |
<section> |
| 103 |
<title>Introduction</title> |
| 104 |
<body> |
| 105 |
-<p>All Gentoo developers were users of Gentoo before they became developers. Our users aren't just the reason Gentoo exists today; they're our future volunteers too.</p> |
| 106 |
+<p>All Gentoo developers were users of Gentoo before they became developers and still are users. Our users aren't just the reason Gentoo exists today; they're our future volunteers too.</p> |
| 107 |
|
| 108 |
<p>If you start contributing to a project, we'll give you write access to the |
| 109 |
project's overlay, and we'll provide mentors to help you contribute. |
| 110 |
Eventually, if we like what you do and the way you do it, we'll invite you to |
| 111 |
-go the whole hog and become a full Gentoo developer, with a nice shiny |
| 112 |
-@g.o email address.</p> |
| 113 |
+go the whole hog and become a full Gentoo developer.</p> |
| 114 |
</body> |
| 115 |
</section> |
| 116 |
|
| 117 |
@@ -173,15 +175,22 @@ |
| 118 |
out on IRC, and may have their own channels for their projects. Examples of |
| 119 |
these include the PHP project (#gentoo-php), and the Webapps project |
| 120 |
(#gentoo-web). Others prefer to be contacted by email only. The only way |
| 121 |
-you'll find out is to try and make contact, and take it from there.</p> |
| 122 |
+you'll find out is to try and make contact, and take it from there. Commonly people in #gentoo-bugs on freenode IRC know where to find the people in question.</p> |
| 123 |
</body> |
| 124 |
</section> |
| 125 |
|
| 126 |
<section> |
| 127 |
<title>Working With Subversion</title> |
| 128 |
<body> |
| 129 |
-<p>You'll need to get comfortable working with Subversion. Subversion is the |
| 130 |
-version control software we use to manage the contents of our overlays. 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> |
| 131 |
+<p>Subversion is one version control software we use to manage the contents of our overlays. If you have never used Subversion before, the Subversion book is an excellent way to learn Subversion. You can buy it in dead-tree format if you prefer or read it online for free. |
| 132 |
+</p> |
| 133 |
+</body> |
| 134 |
+</section> |
| 135 |
+ |
| 136 |
+<section> |
| 137 |
+<title>Working With Git</title> |
| 138 |
+<body> |
| 139 |
+<p>Git is another version control software we use to manage the contents of our overlays. To get in touch with it, see the tutorial provided on the homepage.</p> |
| 140 |
</body> |
| 141 |
</section> |
| 142 |
|
| 143 |
@@ -200,7 +209,7 @@ |
| 144 |
<body> |
| 145 |
<p>Q: Do you host overlays for users?</p> |
| 146 |
<ul> |
| 147 |
-<li>A: No, we do not. If you want an overlay of your own on o.g.o, you must first become a Gentoo developer.</li> |
| 148 |
+<li>A: No, we do not. If you want an overlay of your own on (git.)overlays.gentoo.org, you must first become a Gentoo developer.</li> |
| 149 |
</ul> |
| 150 |
</body> |
| 151 |
</section> |
| 152 |
|
| 153 |
|
| 154 |
|
| 155 |
1.15 xml/htdocs/proj/en/overlays/devguide.xml |
| 156 |
|
| 157 |
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/overlays/devguide.xml?rev=1.15&view=markup |
| 158 |
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/overlays/devguide.xml?rev=1.15&content-type=text/plain |
| 159 |
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/overlays/devguide.xml?r1=1.14&r2=1.15 |
| 160 |
|
| 161 |
Index: devguide.xml |
| 162 |
=================================================================== |
| 163 |
RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/overlays/devguide.xml,v |
| 164 |
retrieving revision 1.14 |
| 165 |
retrieving revision 1.15 |
| 166 |
diff -u -r1.14 -r1.15 |
| 167 |
--- devguide.xml 12 Oct 2008 09:57:06 -0000 1.14 |
| 168 |
+++ devguide.xml 30 Oct 2008 19:35:20 -0000 1.15 |
| 169 |
@@ -19,8 +19,8 @@ |
| 170 |
|
| 171 |
<license/> |
| 172 |
|
| 173 |
-<version>2.1</version> |
| 174 |
-<date>2008-10-12</date> |
| 175 |
+<version>2.2</version> |
| 176 |
+<date>2008-10-30</date> |
| 177 |
|
| 178 |
<chapter> |
| 179 |
<title>Introduction</title> |
| 180 |
@@ -33,19 +33,11 @@ |
| 181 |
</section> |
| 182 |
|
| 183 |
<section> |
| 184 |
-<title>What is overlays.gentoo.org?</title> |
| 185 |
-<body> |
| 186 |
-<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> |
| 187 |
-</body> |
| 188 |
-</section> |
| 189 |
- |
| 190 |
-<section> |
| 191 |
<title>Who Can Use overlays.gentoo.org?</title> |
| 192 |
<body> |
| 193 |
-<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> |
| 194 |
+<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> |
| 195 |
|
| 196 |
-<p>Any Gentoo staff member or user (ie, anyone who doesn't have write access to |
| 197 |
-the main Portage package tree) can download and use the contents of any hosted |
| 198 |
+<p>Any User can download and use the contents of any hosted |
| 199 |
overlay. If you choose, you can also give users write access to your |
| 200 |
overlay.</p> |
| 201 |
</body> |
| 202 |
@@ -54,12 +46,10 @@ |
| 203 |
<section> |
| 204 |
<title>What Does overlays.gentoo.org Give Me?</title> |
| 205 |
<body> |
| 206 |
-<p>The overlays.gentoo.org service currently provides:</p> |
| 207 |
+<p>The (git.)overlays.gentoo.org service currently provides:</p> |
| 208 |
<ul> |
| 209 |
-<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> |
| 210 |
-<li><uri link="http://subversion.tigris.org">Subversion</uri> - a centralised version control system</li> |
| 211 |
+<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> |
| 212 |
<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> |
| 213 |
-<li><uri link="http://git.or.cz">Git</uri> - Fast Version Control System</li> |
| 214 |
<li><uri link="http://git.or.cz/gitwiki/Gitweb">gitweb</uri> - provides full-fledged web interface for viewing Git repositories.</li> |
| 215 |
</ul> |
| 216 |
|
| 217 |
@@ -142,14 +132,11 @@ |
| 218 |
<section> |
| 219 |
<title>Project Overlays</title> |
| 220 |
<body> |
| 221 |
-<p>"Project" overlays are overlays for official Gentoo projects. A good |
| 222 |
-example is <uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.</p> |
| 223 |
+<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> |
| 224 |
|
| 225 |
<p>An official Gentoo project is a project that has a project page on |
| 226 |
-www.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 |
| 227 |
-metastructure document</uri>, which is Gentoo's governing document). The project |
| 228 |
-lead(s) are responsible for the project overlay, including its contents, and |
| 229 |
-any problems it causes other Gentoo projects and developers.</p> |
| 230 |
+www.gentoo.org, and that has an elected lead. (This definition comes from the |
| 231 |
+metastructure 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> |
| 232 |
|
| 233 |
<p>To request a SVN project overlay, the project's lead just needs to pop into |
| 234 |
#gentoo-overlays on IRC and ask for an overlay to be created. Or, if he/she |
| 235 |
@@ -170,7 +157,6 @@ |
| 236 |
repository</li> |
| 237 |
<li>give write access to all project members who already have an o.g.o |
| 238 |
account</li> |
| 239 |
-<li>contact all of the other project members, and sort out their access</li> |
| 240 |
</ul> |
| 241 |
|
| 242 |
<p>For an Git request, we will:</p> |
| 243 |
@@ -180,10 +166,8 @@ |
| 244 |
<li>create an git.o.g.o account for you if you don't already have one</li> |
| 245 |
<li>give you write access to your overlays Git repository</li> |
| 246 |
<li>give write access to all project members who already have an o.g.o account</li> |
| 247 |
-<li>contact all of the other project members, and sort out their access</li> |
| 248 |
</ul> |
| 249 |
|
| 250 |
- |
| 251 |
</body> |
| 252 |
</section> |
| 253 |
|
| 254 |
@@ -192,7 +176,7 @@ |
| 255 |
<body> |
| 256 |
|
| 257 |
<p>"Developer" overlays are overlays owned by individual Gentoo developers. One |
| 258 |
-example is <uri link="http://overlays.gentoo.org/dev/tcort">tcort's overlay</uri>.</p> |
| 259 |
+ example is <uri link="http://overlays.gentoo.org/dev/beandog">beandog's overlay</uri>.</p> |
| 260 |
|
| 261 |
<p>If you have an @gentoo.org email address, and you've passed the ebuild quiz, |
| 262 |
then you can have your own developer overlay on o.g.o.</p> |
| 263 |
@@ -229,8 +213,7 @@ |
| 264 |
<body> |
| 265 |
<p>Because o.g.o is designed to support a blend of both Gentoo developers and |
| 266 |
Gentoo users, we don't create 'real' system-level accounts on the o.g.o host. |
| 267 |
-All access is currently through Apache, and is managed by Apache htpasswd and |
| 268 |
-htgroup files.</p> |
| 269 |
+</p> |
| 270 |
|
| 271 |
<impo>You do *not* have SSH access to o.g.o.</impo> |
| 272 |
</body> |
| 273 |
@@ -295,25 +278,7 @@ |
| 274 |
|
| 275 |
<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> |
| 276 |
|
| 277 |
-<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> |
| 278 |
- |
| 279 |
-<p>We have installed several Trac plugins, which we hope will make your wiki even |
| 280 |
-more useful to you. If you come across any additional plugins that you'd like |
| 281 |
-to see installed, please let us know, and we'll take a look at them.</p> |
| 282 |
- |
| 283 |
-<ul> |
| 284 |
-<li><e>LayOnTrac</e> - lists the packages from the overlay.</li> |
| 285 |
-<li><uri link="http://muness.textdriven.com/trac/wiki/tags/Setup">TracTags</uri> - displays a tag cloud</li> |
| 286 |
-<li><uri link="http://trac.edgewall.org/wiki/WebAdmin">TracWebAdmin</uri> - provides web-based admin panel for Trac</li> |
| 287 |
-</ul> |
| 288 |
- |
| 289 |
-<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> |
| 290 |
- |
| 291 |
-<ul> |
| 292 |
-<li><uri link="http://trac-hacks.org/wiki/AddCommentMacro">AddComment</uri> - allows visitors to add comments to the bottom of your pages</li> |
| 293 |
-<li><uri link="http://trac-hacks.org/wiki/FootNoteMacro">FootNote</uri> - adds support for adding footnotes to a page</li> |
| 294 |
-<li><uri link="http://trac-hacks.org/wiki/TocMacro">TOC</uri> - adds support for publishing a Table of Contents on a page</li> |
| 295 |
-</ul> |
| 296 |
+<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> |
| 297 |
|
| 298 |
</body> |
| 299 |
</section> |
| 300 |
@@ -321,9 +286,9 @@ |
| 301 |
<section> |
| 302 |
<title>Getting Started With Subversion</title> |
| 303 |
<body> |
| 304 |
-<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> |
| 305 |
+<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> |
| 306 |
|
| 307 |
-<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> |
| 308 |
+<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> |
| 309 |
|
| 310 |
<p>Here are some basic commands to get you started.</p> |
| 311 |
<pre caption="Checking out your overlay">svn co https://overlays.gentoo.org/proj/php</pre> |
| 312 |
@@ -399,11 +364,6 @@ |
| 313 |
to the Gentoo Portage package tree can have write access to one or more |
| 314 |
overlays. Several Gentoo projects have found that this is a great way to train |
| 315 |
and evaluate potential Gentoo developers in a safe environment.</p> |
| 316 |
- |
| 317 |
-<p>At the moment, only the Overlays team can update the access control lists for |
| 318 |
-overlays.gentoo.org. We will provide a web-based tool for managing the access |
| 319 |
-control lists at a later date. But, for now, if you need a change made, |
| 320 |
-please drop by #gentoo-overlays on IRC for assistance.</p> |
| 321 |
</body> |
| 322 |
</section> |
| 323 |
|
| 324 |
@@ -551,10 +511,8 @@ |
| 325 |
|
| 326 |
<p>Q: Why can't I edit the access control list directly?</p> |
| 327 |
<ul> |
| 328 |
-<li>A: (SVN) The access control list currently lives in htpasswd / htgroup files used |
| 329 |
- by Apache. Only o.g.o admin staff have ssh access into the o.g.o box.</li> |
| 330 |
-<li>A: (Git) The access control list currently lives in the gitosis-admin repository, |
| 331 |
- which is writable only by the o.g.o staff.</li> |
| 332 |
+<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> |
| 333 |
+<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> |
| 334 |
</ul> |
| 335 |
</body> |
| 336 |
</section> |
Archives