Project:Overlays/Internal Overlays team guide

This guide outlines the basic procedures for doing Overlays team work.

User requests
All user requests should be handled via Bugzilla, with specific details being logged in bug comments.

If users send requests via e-mail, please ask them to file a bug instead. Having a Bugzilla account is also obligatory.

If owner no longer has access to his original Bugzilla account, attempt to verify his identity (e.g. GitHub account owning the repository). If he is no longer interested in participating and requests removing the repository, this request can be handled by e-mail.

Before adding a repository
Before adding a new repository, please verify at least the following:


 * 1) that it has profiles/repo_name file matching requested repository name (and not colliding with any existing repositories):
 * 2) * if repo_name differs from requested name, ask user if he prefers updating repo_name or adding with the current name from repo_name,
 * 3) * if repo_name collides with existing repository and the repository is unmaintained, you may propose to take over the name if the original owner agrees or doesn't respond in reasonable time.
 * 4) that it has metadata/layout.conf specifying appropriate masters= entry.
 * 5) * if masters is empty, ensure that the repository can work stand-alone (I.e. doesn't depend on packages or eclasses from ::gentoo),
 * 6) * if masters specifies additional repositories, make sure they are all in repositories.xml.
 * 7) that there are no obvious failures ;-),
 * 8) that the user requesting the repository is its maintainer. If he's not, there are two possibilities:
 * 9) * the owner needs to have a Bugzilla account and agree to adding him as the owner (i.e. having all bugs assigned to him),
 * 10) * the owner needs to agree on being proxied by the requesting person, and the requesting person is then responsible for proxying all the bugs and other requests.
 * 11) that the user doesn't request another e-mail for the owner than for Bugzilla account:
 * 12) * if he does, get a confirmation that he either needs to have that registered on Bugzilla as well, or that he is fine with using his Bugzilla e-mail.

If repositories.xml is provided, make sure it is correct and update it as appropriate (see below). Otherwise, just write it from scratch.

Adding to repositories.xml
The repositories.xml file is stored in data/api.git repository (files/overlays/repositories.xml). All Gentoo developers and staffers have write access (i.e. you may ask another developer to add his repository himself).

After updating the file, verify it:

Commit with OpenPGP signature, start commit message with repositories:, add a bug no and push (--signed).

Few tips for adding repositories.xml entries:
 * always use   from repo_name (otherwise, there will be a mismatch post adding),
 * sort repositories lexically by name,
 * all   entries (there can be more than one) have to match valid Bugzilla accounts,
 * sources:
 * https:// is preferred as it is secured and reachable behind restricted firewalls,
 * avoid ssh or make it last choice as it may trigger undesired password queries.

Updating and removing from repositories.xml
Similar rules as when adding new entries apply.

Usually modifications and removals should be done on request of owners, or with confirmations from them.

Exceptions are:
 * if repo_name changes and owner doesn't respond to the bug in reasonable time, you can update   to match it (remember to reorder the entries!),
 * if there are problems with the repository or it is long-unmaintained, and the owner doesn't respond to the bugs, you can remove it,
 * if there are major issues with the repository doing harm to users (major security problems, damage to systems), you can remove it without waiting for response (and re-add when the issue is fixed).

When removing repositories, it would be nice to make sure we don't remove masters of other repositories. However, there is no good infrastructure to test this beforehand, so we may just wait for repo-mirror-ci to complain about it afterwards.