Project:Overlays/Old Policy

Warning
This document is kept only for historical purposes. The current guide is maintained as Project:Overlays/Overlays guide.

This is the policy document governing the Gentoo Overlays service.

Introduction

Here are the policies for the overlays.g.o service. If you host an overlay on overlays.g.o, or if you participate in the administration of overlays.g.o, you must follow these policies.

What is the overlays.g.o service?

overlays.g.o provides a social workspace, for Gentoo projects and developers to publish their Gentoo package overlays in one location, where it's easy for devs and non-devs alike to collaborate.

Types of overlay

overlays.g.o hosts two types of overlay:

overlays for Gentoo project teams
overlays for individual Gentoo developers
overlays for Gentoo summer of code projects
overlays for other Gentoo-specific projects that are external

Project overlays

"Project overlays" are overlays owned by recognized Gentoo project teams. Such teams are required to meet the definition of a project that you can find in our metastructure document.

"Project overlays" will have the same name as the Gentoo project team. Each project is only allowed a single overlay.

As far as this policy is concerned, project overlays are owned by the elected lead(s) of the project.

Developer overlays

"Developer overlays" are overlays owned by individual Gentoo developers. These are the developers who have successfully taken the Gentoo developer quizzes, and who have been given commit access to the main Gentoo package tree.

Each "developer overlay" will have the same name as the developer who owns the overlay. Each developer is only allowed a single overlay.

As far as this policy is concerned, developer overlays are owned by the individual Gentoo developer who asked for the overlay to be hosted.

Summer of Code overlays

"Summer of Code overlays" are overlays that were created for the express purpose of hosting the development of a Google Summer of Code (SoC) project for Gentoo.

Each "SoC overlay" will be named for the SoC project. Multiple overlays may exist if required by the project.

As far as this policy is concerned, SoC overlays are owned by the SoC student.

External Gentoo-specific overlays

TODO

Responsibilities

Infra are responsible for the platform (hardware + o/s) that overlays.g.o is hosted on.
The overlays project team is responsible for administering the overlays.g.o service, including responsibility for the software used to deliver the service (e.g. svn, trac, git, gitweb).
Overlay owners are responsible for the contents of their overlays, and for the conduct of anyone who has commit access to their overlays.
Any individual committing to an overlay is responsible for his/her own actions.

Creating overlays

Overlays are created at the request of whoever will be the owner of the overlay.

Overlays are optional; no Gentoo developer or project team is required to setup an overlay.

Gentoo developers are free to host their overlays somewhere else.

Commit access to overlays

To be clear:

A "developer" is someone who has commit access to the main Gentoo package tree.
A non-developer is anyone who doesn't have commit access to the main Gentoo package tree. That includes other members of Gentoo staff.

Project overlays:

Any developer listed on a team's project page can have commit access to that team's overlay(s). Just ask the overlays admin team to sort you out with access.
Any dev not listed on a team's project page can have commit access, with the agreement of a member of the project team.
Any non-dev can have commit access to a team's overlay(s). The request for access has to come from the owner of the overlay.

Developer overlays:

Any Gentoo dev can ask for commit access, with the agreement of the overlay's owner.
Any non-dev can have commit access to a developer's overlay. The request for access has to come from the owner of the overlay.

SoC overlays:

The SoC student mentor and student will be provided with the overlay.
Any non-dev can have commit access to a SoC's overlay. The request for access must come from either the SoC student or his mentor.

External overlays:

TODO

Common requirements for non-devs

The non-dev is required to have registered their nick on Freenode IRC first, and must provide a valid email address for our records.
If you're a non-dev, please don't ask the overlays team directly for access, as refusal often offends.

Note
With trac + svn, it's possible to give commit access separately to trac (ie, the wiki), and svn.

General rules for overlays

We're deliberately trying to keep the rules on overlays to a minimum. Please, don't abuse the service, and force us to add more rules :(

What you can and cannot store on overlays.g.o

overlays.g.o is for hosting package trees, their patchsets, any docs, and any downloadable tarballs that have nowhere else to be hosted.

TODO: Note that $UPSTREAM is allowed for Gentoo-specific/related.

Overlays are public

There are no "secret" overlays.

All overlays are listed on the frontpage of overlays.g.o, and anyone is free to download the contents of an overlay.

If you need a secret overlay, we're not the service for you.

Bug tracking

bugs.g.o is the OneTrueBugTrackingSystem(tm), even for overlays.

Moving contributions from overlays to the Portage tree

Don't set up anything to automatically commit the contents of an overlay to the main Gentoo package tree. Ever.

Any code you take from an overlay and commit to the main Gentoo package tree needs to be thoroughly reviewed first. As the person committing the code to the main tree, it's your responsibility to ensure that the code meets the required standards.

Administration of overlays

Only the overlays.g.o administration team (listed on the overlays project page) have shell access into the overlays.g.o box. At the moment, account management (including resetting passwords) has to be done through the overlays administration team.

If you need anything doing to your overlay (adding/removing a user f.ex), please ask in #gentoo-overlays (webchat), and someone will help you as soon as possible.

Removal of overlays

Overlays can be removed at the discretion of the overlays administration team. Except for exceptional circumstances, we'll only remove overlays for the following reasons:

Project overlays will be removed if the project closes down.
Developer overlays will be removed when its owner retires.

Exceptional circumstances may include:

Complaints from other developers about the contents of an overlay causing problems for packages in the main tree.
Complaints from other developers about the contents of an overlay creating a security risk to our users.

All exceptional circumstances will be discussed on gentoo-dev before action is taken.

Important
Overlays are places where experimental changes can be made and tested. Please make sure you understand why things are the way they are in an overlay before you make a complaint about what's going on!

Restrictions on new software

We're always willing to listen to requests for different software we could offer as part of the service. Please bear in mind that we need to keep the amount of software offered to a minimum, to reduce the workload on the overlays administration team.

Any new software added to the service will have to meet the following requirements *as a minimum*. Please don't ask for a piece of software unless you've checked and made sure it meets these requirements.

There must be a working package for the software in Portage.
The package must have an active maintainer.
The package must have a "credible" security history. In particular, packages that need regular updating to fix security holes are likely to be rejected.
If the package provides a bug-tracking system, it must be possible to disable the bug-tracking system.

The only access to overlays.g.o is via these two mechanisms:

HTTP/HTTPS and Apache
SSH to Gitosis for Git overlays

The security mechanism for overlays.g.o is via HTTP basic auth, over SSL. We use both htpasswd and htgroup files to manage who can commit where.

A package can have finer-grained control via its own security mechanisms (e.g. trac's permissions list), but the package must be compatible with these access and security restrictions.

Errors and omissions

If you find a fault with this policy, please file a bug on bugs.g.o, and assign it to overlays@gentoo.org.

All policy changes will first be posted to gentoo-dev for discussion.

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Stuart Herbert, Markus Ullmann, and Robin H. Johnson
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.