Gentoo Development Guide

The Portage Tree

The basic layout of the portage tree is as follows:

What Belongs in the Tree?

Things that do not belong in the tree:

  • Large patches
  • Non-text files
  • Photos of teletubbies
  • Files whose name starts with a dot

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).