Project:Overlays/Overlays guide

Basic rules
The Gentoo Overlays project members maintain the global repository list that powers layman, overlays.gentoo.org and many more Gentoo-oriented services. If you are looking to have your repository listed there, we are here to help.

There are a few rules that must be met by all repositories on the list. Those are:
 * 1) The repository must be publicly accessible through one of the protocols/VCS-es supported by layman. For best portability, git+https:// is recommended.
 * 2) The repository must meet the minimal QA standards: have a valid and unique repository name (in profiles/repo_name, layout.conf is not portable), and have a valid masters= entry in metadata/layout.conf).
 * 3) The repository owner must have a Gentoo Bugzilla account. Bugzilla will be used for all official communications regarding the repository.
 * 4) The repository should be maintained with best effort not to cause issues to users using it. We reserve the right to remove repositories that are reported to pose serious threat to our users.

The repositories can be hosted on your own infrastructure, any public hosting service, or we can host it on git.gentoo.org for you (git only). In the latter case, we also support automatically populating external mirrors of the repository (e.g. on GitHub).

Requesting adding repository hosted elsewhere
If your repository is already hosted somewhere, please create a bug in Gentoo Infra product, Gentoo Overlays component and provide the following information:


 * 1) requested repository name (must be equal to one in profiles/repo_name, filling it is just a confirmation),
 * 2) short description,
 * 3) homepage URL,
 * 4) repository owners,
 * 5) repository type and URLs,
 * 6) repository commit feed URLs (if any).

Alternatively, you can provide a repositories.xml-format file for your repository and we will copy the information from it.

Note that if you are not the repository owner, you will have to obtain his explicit permission to have the repository added. He will also have to meet the Bugzilla account requirement.

Requesting hosting for a repository
If you would like us to host the repository for you, please create a bug in Gentoo Infra product, Gentoo Overlays component and provide the following information:


 * 1) requested repository name in repo/user/... namespace (the URL will be git.gentoo.org/repo/user/...),
 * 2) short description,
 * 3) external homepage URL if you are planning to use one,
 * 4) your public SSH key if you have not provided one for git.gentoo.org before,
 * 5) a list of other people (and their public SSH keys, if appropriate) who should have write or admin access.

This bug will serve both the purpose of creating the git repository and adding it to the list.

Please note that you will be required to accept the following terms of service:

-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- Use of this service is  limited to overlays containing ebuilds and supporting  files  (e.g.  init.d  scripts,  configuration  files, patches,  but not distfiles)  and must follow  the same guidelines as apply to the gentoo-x86 tree of Gentoo. Any or all uses of this service and all files on this service may be  intercepted,  monitored, recorded,  copied,  audited, inspected, and disclosed to authorized site personnel, as well as authorized officials of federal law  enforcement agencies, both domestic and foreign. By using this service,  the user consents to such interception, monitoring, recording, copying, auditing, inspection, and  disclosure  at  the discretion  of  authorized site  personnel. Use of this  service constitutes consent to security monitoring and testing. All activity is logged with  your host name  and IP address. Unauthorized or improper use of this service  may result in civil and criminal penalties. By continuing to use  this service  you indicate your awareness of and consent to these terms and conditions of use. -- Gentoo Linux Infrastructure Admins CEASE USE IMMEDIATELY, if you do not agree to the conditions stated in this warning. ******************* -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

Reporting bugs on repositories
If you would like to report a bug regarding a third-party repository or a package in it, you can either use the repository-specific bugtracker (if any) or the Gentoo Bugzilla. If the request requires explicit action from Gentoo Overlays project members (e.g. removing the repository), it has to be carried via Gentoo Bugzilla.

When reporting bugs on packages in third-party repositories in Gentoo Bugzilla, please remember to explicitly mention from which repository the package comes from. This is usually done using ::repository-name notation (alike Portage). This will ensure that the bug is properly assigned to the repository owner, rather than the maintainer of respective package in Gentoo.