Gentoo Overlays: Users' Guide

Who Can Use overlays.gentoo.org? -

Any Gentoo project, or Gentoo developer, can have their own overlay h= osted on overlays.gentoo.org, with the RSS feed from the changelog includ= ed on the overlays.gentoo.org ho= mepage.

Any Gentoo project, or Gentoo developer, can have their own overlay h= osted on (git.)overlays.gentoo.org, with the RSS feed from the changelog = included on the overlays.gentoo.= org planet.

=20 -

Any Gentoo staff member or user (ie, anyone who doesn't have write ac= cess to -the main Portage package tree) can download and use the contents of any = hosted +

Any User can download and use the contents of any hosted overlay. If you choose, you can also give users write access to your overlay.

@@ -54,12 +46,10 @@

What Does overlays.gentoo.org Give Me? -

The overlays.gentoo.org service currently provides:

The (git.)overlays.gentoo.org service currently provides:

Trac (a wiki w/ integra= ted subversion browser), for quickly creating and maintaining documentati= on about your overlay
Subversion - a cent= ralised version control system
Trac (a wiki w/ integra= ted subversion browser), for quickly creating and maintaining documentati= on about your Subversion based overlay
Publishing the changelog for your overlay on the o.g.o homepage, so that everyone who's inter= ested can see what's going on
Git - Fast Version Control Syst= em
gitweb - provide= s full-fledged web interface for viewing Git repositories.

=20 @@ -142,14 +132,11 @@

Project Overlays -

"Project" overlays are overlays for official Gentoo projects. A good -example is the PHP Ove= rlay.

"Project" overlays are overlays for official Gentoo projects. An exa= mple is the PHP Overlay= .

=20

An official Gentoo project is a project that has a project page on -www.gentoo.org, and that has an elected lead. (This definition comes fr= om the -metastructure document, which is Gentoo's governing document). Th= e project -lead(s) are responsible for the project overlay, including its contents,= and -any problems it causes other Gentoo projects and developers.

+www.gentoo.org, and that has an elected lead. (This definition comes fr= om the +metastructure document). The project lead(s) are responsible for the pr= oject overlay, including its contents, and any problems it causes other G= entoo projects and developers.

=20

To request a SVN project overlay, the project's lead just needs to po= p into #gentoo-overlays on IRC and ask for an overlay to be created. Or, if he= /she @@ -170,7 +157,6 @@ repository

give write access to all project members who already have an o.g.o account

contact all of the other project members, and sort out their access<= /li> =20

For an Git request, we will:

@@ -180,10 +166,8 @@

create an git.o.g.o account for you if you don't already have one

give you write access to your overlays Git repository

give write access to all project members who already have an o.g.o a= ccount

contact all of the other project members, and sort out their access<= /li> =20 -

=20 @@ -192,7 +176,7 @@ =20

"Developer" overlays are overlays owned by individual Gentoo develope= rs. One -example is tcort's ov= erlay.

+ example is beandog= 's overlay.

=20

If you have an @gentoo.org email address, and you've passed the ebuil= d quiz, then you can have your own developer overlay on o.g.o.

@@ -229,8 +213,7 @@

Because o.g.o is designed to support a blend of both Gentoo developer= s and Gentoo users, we don't create 'real' system-level accounts on the o.g.o = host. -All access is currently through Apache, and is managed by Apache htpassw= d and -htgroup files.

=20 You do *not* have SSH access to o.g.o. @@ -295,25 +278,7 @@ =20

We have disabled the bug tracking system in Trac. Use Gentoo's bugzilla for bug tracking your over= lay.

=20 -

Your overlay's RSS feed - the one that is shown on the o.g.o homepage - comes from Trac's Timel= ine page.

- -

We have installed several Trac plugins, which we hope will make your = wiki even -more useful to you. If you come across any additional plugins that you'= d like -to see installed, please let us know, and we'll take a look at them.

- -

LayOnTrac - lists the packages from the overlay.
Trac= Tags - displays a tag cloud
TracWebAdmin - provides web-based admin panel for Trac

- -

We have installed several Trac macros, which we hope will make your w= iki even more useful to you. If you come across any additional macros th= at you'd like to see installed, please let us know, and we'll take a look= at them.

- -

AddComment<= /uri> - allows visitors to add comments to the bottom of your pages
FootNote - adds support for adding footnotes to a page
TOC - adds s= upport for publishing a Table of Contents on a page

Your overlay's RSS feed - the one that is shown on the o.g.o homepage - comes from Trac's Timel= ine page or GitWeb's summary.

=20

@@ -321,9 +286,9 @@

Getting Started With Subversion -

Your overlay comes with Su= bversion, a modern alternative to CVS. The advantages of Subversio= n over CVS include real versioning of directories, full changeset support= , and it's much easier to do branching if you need to. The main disadvan= tage of Subversion is that it is slower than CVS, and that a local Subver= sion checkout requires more disk space.

The advantages of Subversion over CVS include real versioning of dire= ctories, 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 th= an CVS, and that a local Subversion checkout requires more disk space. =20 -

If you have never used Subversion before, the online book is an excellent way to learn Subver= sion. You can buy it in dead-tree format too if you prefer.

If you have never used Subversion before, the online book is an excel= lent way to learn Subversion. You can buy it in dead-tree format too if = you prefer.

=20

Here are some basic commands to get you started.

svn co https://overlays.gento=
o.org/proj/php

@@ -399,11 +364,6 @@ to the Gentoo Portage package tree can have write access to one or more overlays. Several Gentoo projects have found that this is a great way t= o train and evaluate potential Gentoo developers in a safe environment.

- -

At the moment, only the Overlays team can update the access control l= ists for -overlays.gentoo.org. We will provide a web-based tool for managing the = access -control lists at a later date. But, for now, if you need a change made, -please drop by #gentoo-overlays on IRC for assistance.

=20 @@ -551,10 +511,8 @@ =20

Q: Why can't I edit the access control list directly?

A: (SVN) The access control list currently lives in htpasswd / htgro= up files used - by Apache. Only o.g.o admin staff have ssh access into the o.g.o box= .
A: (Git) The access control list currently lives in the gitosis-admi= n repository,=20 - which is writable only by the o.g.o staff.
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.
A: (Git) The access control list currently lives in the gitosis-admi= n repository, which is writable only by the o.g.o staff.