The Gentoo Repository

The basic layout of the Gentoo repository is as follows:

Categories, for example app-editors, sys-apps
- Category metadata, for example app-admin/metadata.xml
- Package directories for example app-editors/vim
  - Package metadata, for example app-editors/vim/metadata.xml
  - Package Manifest, for example app-editors/vim/Manifest
  - Ebuilds, for example app-editors/vim/vim-6.3.068.ebuild, app-editors/vim/vim-7.0_alpha20050326.ebuild
  - Package files directory, for example app-editors/vim/files
    - Small patches and other miscellaneous files, for example app-editors/vim/files/vim-completion
Eclasses directory, eclass/
Licenses directory, licenses/
Metadata directory, metadata/. Most of the listed contents are not kept directly in the main git tree but instead auto-generated or included from other repositories as part of the Git to Rsync process.
- Various control files, for example layout.conf, timestamp and projects.xml. Only layout.conf exists in the main git tree.
- XML validation files in metadata/dtd/ and metadata/xml-schema/.
- Security advisories in metadata/glsa/ and news items in metadata/news/
Profiles directory, profiles/
- Various control and documentation files, for example categories, info_pkgs, info_vars, package.mask, use.desc
- Updates directory, profiles/updates/
  - Updates files, for example profiles/updates/1Q-2005
- Main profile cascade
Scripts directory, scripts/

What Belongs in the Tree?

Things that do not belong in the tree:

Large patches
Non-text files
Photos of teletubbies
Files whose name contains characters outside [A-Za-z0-9._+-]
Files whose name starts with a dot, a hyphen, or a plus sign

Naming rules for distfiles are more lenient, but for interoperability their filenames are restricted to the printable ASCII range excluding SPACE, i.e., U+0021 to U+007E (see also GLEP 31). Any characters that have a special meaning in Bash or in SRC_URI should also be avoided. If necessary, upstream files can be renamed using -> syntax.

Software-wise, in general all of the following should be met in order for a package to be included in the tree:

Active, Cooperative Upstream: If a package is undeveloped or unmaintained upstream, it can be extremely difficult to get problems fixed. If a package does not have an active upstream, the developers who add the package to the tree must ensure that they are able to fix any issues which may arise.; Sometimes upstream may have a reason for not wanting their package included in the tree. This should be respected.
Reasonably Stable: Keep super-experimental things out of the tree. If you must commit them, consider using package.mask until things calm down, or better yet make them available as overlay ebuilds.
Reasonably Useful: Don't feel obliged to include "Joe's '1337 XMMS Skinz Collection" or "Hans' Super Cool Fast File System" in the tree just because a few users ask for it. Stick to things that might actually be of use.
Properly Packaged: If something is only available in live CVS or dodgy autopackage format, don't include it until upstream can come up with a decent source package. Similarly, avoid things that don't have a proper build system (where relevant) — these are very tricky to maintain.
Patching and Distribution Permitted: If we can't patch packages as necessary ourselves, we end up relying entirely upon upstream for support. This can be problematic, especially if upstream are slow at fixing things. We don't want to be in the situation where we can't stable a critical package because we're still waiting for a closed-source vendor to get their act together.; Similarly, not being able to mirror and distribute tarballs ourselves makes us rely entirely upon upstream mirrors. Experience has shown that these are often extremely unreliable, with files changing, moving or vanishing at random.
Working Ebuilds: If you don't have a working ebuild, don't include it.
Portable: If software is unportable, it's generally because it's badly written. Remember that although x86 has a market majority now, it probably won't in the not too distant future once x86-64 catches on.
Reasonable Security Record: Don't include software that has a terrible security record. Each vulnerability is a lot of work for a lot of people (security teams, arch teams and package maintainers).