Gentoo Logo
Gentoo Logo Side

Gentoo Development Policy


1. General guidelines

Here are some general development guidelines to follow:

  • Always check in your changes with repoman; use repoman commit instead of cvs commit.
  • If a package is either broken in its current version or it has a really nasty build/install process, take a look at how other distributions do it:
  • Your package, when complete and unmasked, is supposed to "just work" for the end-user. Tweaking the installed product to get it to work should be optional; thus you need to install the package with reasonable default settings.
  • Don't be afraid to consult our on-line documentation and ebuilds written and maintained by more senior developers. Feel free to contact senior developers directly with any technical or policy questions.
  • Be cautious about what you commit. Remember that your commits can potentially harm thousands of users. If your commits cause any breakage in the tree, they must be fixed in a timely fashion.
  • Every package must be accompanied by a metadata.xml file which lists - amongst other information - what herd (and/or individual maintainers) are in charge of the package.

2. Specific guidelines


Copyright in ebuilds (and documentation) should always be assigned to Gentoo Foundation. Developers must never put their own names in copyright lines. For more information, please see


On some architectures, shared libraries must be built with -fPIC. On x86 and others, shared libraries will build without -fPIC, but will be wasteful and potentially cause a performance hit. If you encounter a package that is not building shared libraries with -fPIC, patch the Makefile to build only the libraries with -fPIC. There is more information on PIC available at

Gentoo Themes 

While including Gentoo themes in packages is highly encouraged, the default theme (skin/graphics/feel/etc...) must not be changed. The default look and feel should follow the wishes of the upstream developer.


New Perl modules are to be added to portage only when one of the following conditions is met:

  • The module(s) fulfill a dependency
  • The module(s) cannot be handled by g-cpan
  • The module(s) add functionality to existing ebuilds
  • The module(s) provide tools, applications or other features (i.e. more than what their .PM offers)

Please make sure that at least one member of the perl herders approves your addition.

3. Ebuild policy

Naming policy 

Ebuild file names consist of four logical sections:


Note: The brackets ({}) delineate optional fields and do not appear in the literal package name. # represents any non-zero positive integer.

The first section, pkg, is the package name, which should only contain lowercase letters, the digits 0-9, and any number of single hyphen (-), underscore (_) or plus (+) characters. Examples: util-linux, sysklogd, glibc. We have some packages in Portage that do not follow these rules, but your packages should.

The second section, ver, is the version of the package, which should normally be same as the version on the main source tarball. The version is normally made up of two or three (or more) numbers separated by periods, such as 1.2 or 4.5.2, and may have a single letter immediately following the last digit; e.g., 1.4b or 2.6h. The package version is joined to the package name with a hyphen. Examples: foo-1.0, bar-2.4.6.

The third section, {_suf{#}}, is optional may contain one of these predefined suffixes, listed in least-recent to most-recent order:

Suffix Meaning
_alpha Alpha release
_beta Beta release
_pre Prerelease
_rc Release candidate
(none) Normal release
_p Patch level (normally accompanied by trailing integer)

Any of these suffixes may be immediately followed by a non-zero positive integer, e.g., linux-2.4.0_pre10. Assuming identical version parts, the suffixes are ordered as follows (lower means older): _alpha < _beta < _pre < _rc < (no suffix) < _p.

When comparing identical suffixes with trailing integers, the one with the larger integer will be considered most recent. Example: foo-1.0_alpha4 is more recent than foo-1.0_alpha3.

The fourth section of the package name is the Gentoo Linux-specific revision number ({-r#}). This section, like the suffix, is also optional. # is a non-zero positive integer; e.g., package-4.5.3-r3.

This revision number is independent of the version of the source tarball and is used to inform people that a new and improved Gentoo Linux revision of a particular package is available. Initial releases of ebuilds must have no revision number; e.g., package-4.5.3 and are considered by Portage to have a revision number of zero. This means that counting goes as follows: 1.0 (initial version), 1.0-r1, 1.0-r2, etc.

Versioning and revision bumps 

Package revision numbers should be incremented by Gentoo Linux developers when the ebuild has changed to the point where users would want to upgrade. Typically, this is the case when fixes are made to an ebuild that affect the resultant installed files, but the ebuild uses the same source tarball as the previous release. If you make an internal, stylistic change to the ebuild that does not change any of the installed files, then there is no need to bump the revision number. Likewise, if you fix a compilation problem in the ebuild that was affecting some users, there is no need to bump the revision number, since those for whom it worked perfectly would see no benefit in installing a new revision, and those who experienced the problem do not have the package installed (since compilation failed) and thus have no need for the new revision number to force an upgrade. A revision bump is also not necessary if a minority of users will be affected and the package has a nontrivial average compilation time; use your best judgement in these circumstances.

Important: Whenever you create a new revision of an ebuild, be sure to update the ChangeLog file in the ebuild directory. Failing to do so is considered to be in very poor taste and may result in disciplinary action.

Ebuilds should be based on the previous version of the ebuild to ensure that fixes aren't dropped accidentally. Fixes should include appropriate comments in the ebuild explaining what they are for and why they are needed. If you are not familiar with the fixes, or unable to determine if they are still needed, you should not be updating the ebuild.


Portage supports a concept called "virtual" packages. Using virtual packages, it is possible to have a particular category/package name map to another.

Here's an example of how to use virtual packages. Let's say you create a new cron package called foocron. Gentoo Linux is currently set up so that things that need a cron package of some kind depend on the virtual/cron package. This allows ebuilds to ensure that there is some kind of cron available while allowing users the flexibility to install the cron package that they prefer. To plug your foocron-1.0.ebuild into this system, you'd add a line to the ebuild that reads:

Code Listing 3.1


Now, when foocron-1.0 is installed, the virtual/cron package will be registered. If you didn't have any cron package installed before, this would mean that any package depending on virtual/cron would have that dependency fully satisfied. Note that it is possible to specify a PROVIDE value for any type of package -- it need not begin with virtual/. However, you should use the virtual/ category unless you are using the PROVIDE functionality to handle packages that have been renamed.

There is a second component to the Gentoo Linux virtuals implementation. What would happen if there were no installed package that provided virtual/cron? How would Portage choose the "correct" cron to install to satisfy the virtual/cron dependency? Portage takes care of this situation by using a profile-specific virtual mapping file called virtuals which is stored in the profile directory /etc/make.profile. If you take a look at your virtuals file, you'll find that the contents look something like this:

Code Listing 3.2: Sample virtuals file

virtual/lpr             net-print/cups
virtual/python          dev-lang/python
virtual/mta             net-mail/ssmtp

The first line of this file tells Portage that if a package depends on virtual/lpr and no virtual/lpr is installed and no virtual/lpr package is available in the Portage tree, then net-print/cups should be installed to satisfy this dependency. net-print/cups contains a line that reads PROVIDE="virtual/lpr" so that future dependencies on virtual/lpr will be satisfied.

Now for the developer guidelines. If you were to add the foocron package, you would obviously want to ensure that all programs that depend upon virtual/cron are able to work correctly with it. And if you were to add a package named foobarosity that depended on virtual/cron, you should likewise ensure that all packages that provide virtual/cron will be satisfactory for the proper functioning of foobarosity.

Before creating new virtual packages, please begin a discussion on the internal developer mailing list about that virtual. Keeping developers informed of new virtuals is essential to ensure their uniform use.

CVS sources policy 

There are two different ways to build an ebuild based on sources from a CVS development tree. The first and traditional way is to create a "CVS snapshot" ebuild by creating your own tarball snapshot of the upstream CVS tree, mirroring the sources on our official distfile repository, and writing an ebuild to specifically use this tarball snapshot. These types of CVS ebuilds will be referred to as "CVS snapshot ebuilds" below.

The other method of creating a CVS-based ebuild is to use cvs.eclass to create a "live" CVS ebuild. Such an ebuild will dynamically grab the latest development sources from a CVS repository at "fetch" time, ensuring that the sources are as up-to-date as possible. These types of CVS ebuilds will be referred to as "'live' ebuilds" below.

The following paragraphs detail the policy relating to the use of CVS-based ebuilds. Note that there are strict rules relating to the addition of such ebuilds to the Portage tree.

Snapshot cvs ebuilds are greatly preferred over "live" cvs.eclass cvs ebuilds.

Snapshot cvs ebuilds are allowed if a cvs snapshot contains known fixes that are needed for proper operation of a software package, or if the cvs version of a particular software package is known to or has been proven to simply "work better" than the normal release version.

"Live" cvs.eclass ebuilds are generally only intended for the convenience of developers and should always be masked with a ~[arch] keyword. It is impossible to guarantee the reliability of a "live" cvs.eclass ebuild since the upstream cvs tree may change at any time, which is why they should always be masked.

Whether a "live" cvs ebuild or a "snapshot" CVS ebuild, you the developer are responsible for ensuring that the ebuild works correctly. This is particularly difficult to do with "live" cvs ebuilds for obvious reasons.

If ebuilds (of any kind) do not work correctly or are flaky, they should be fixed or removed from the Portage tree. If they are "live" ebuilds, they may be ~[arch] keyword masked for their lifetime (this special exception is detailed below).

If a user or users specifically request a "live" cvs ebuild, you can add one for them. It should have a ~[arch] keyword so that other users don't merge it unsuspectingly.

This way, the user(s) requesting them (likely developers) can install them but other users will be protected from merging them accidentally. Again, this only applies to situations where a user or users specifically request a "live" cvs.eclass CVS ebuild. Snapshot ebuilds should only be added to the Portage tree with the intention that they are stable and provide better functionality than the normal release versions of said software.

Important: Snapshot ebuilds of pre-release CVS sources should be named as follows: foo-x.y_preYYYYMMDD.ebuild. foo is the package name, x.y is the version number of the upcoming release, _pre is a literal string, and YYYYMMDD is a timestamp of the day the CVS snapshot was taken. Use this naming convention to ensure that a x.y.1 release version won't be considered to be older than a x.y snapshot, while at the same time ensuring that the official x.y release will be considered newer than your CVS snapshot version. For CVS snapshots of already-released CVS sources, use the format foo-x.y_pYYYYMMDD.ebuild (notice the _p for "patchlevel.") This will ensure that your CVS ebuild will be considered newer than the standard x.y release.

Important: Currently, the policy for naming "live" cvs ebuilds is to ensure that the package name ends with -cvs. In the future, a _cvs version suffix will likely be added to Portage and this policy will be updated.

User-submitted ebuilds 

User-submitted ebuilds should never be blindly trusted and should always be well-tested and audited before being committed to CVS. If a user-submitted ebuild has problems, you will be held accountable. By committing it to CVS, you are vouching that the ebuild meets all Gentoo Linux development standards.

Make sure that the user-submitted ebuild doesn't contain custom headers like this:

Code Listing 3.3: A custom header that should be transferred to the ChangeLog

# Ebuild updated by: me <[email protected]>

This information should be added to the ChangeLog using proper ChangeLog comment syntax. Always ensure that the ChangeLog gives proper credit to the user who submitted the ebuild. This information should appear in the first ChangeLog entry.

Also ensure that any new ebuilds you commit contain the following line:

Code Listing 3.4

# $Header: $

Quite a few user-submitted ebuilds are based on files from rsync, which can contain incorrect header lines.

Encourage users to submit diffs to existing ebuilds if they are submitting an upgrade. By doing this, we can help avoid the re-introduction of previously-fixed bugs into our "new" ebuilds. If you are not working from a user-submitted diff but a complete ebuild, then use the diff command to see what has changed, keeping an eye open for anything from our current ebuild that should appear in the new ebuild, or anything in the new ebuild that should be fixed or removed.

In general, let the user do the work required to get his or her ebuild up to par, unless you want to clean up the ebuild on his or her behalf. Even so, it's often better to have the user do the work so that they can learn from their mistakes and submit cleaner ebuilds in the future. Be sure to be thankful for any submission, even if it isn't very good. Be polite but honest -- if an ebuild isn't usable, the user can be told in a way that does not insult their current ebuild-writing abilities. Remember that the user who submitted that broken ebuild may be a skilled and productive member of our project in the future -- that is, if they receive the right amount of encouragement and support and continue to improve in their abilities.

4. QA policy

Portage release policy 

Note: As of 17 Dec 2002, Nick Jones (carpaski) is the Portage Maintainer.

Only the Portage Maintainer has the authority to roll new releases of Portage for use by users, either masked or unmasked versions. No one else is allowed to roll new releases of Portage.

The only exception to this rule is for situations where the Portage Maintainer may be unavailable for extended periods of time and there is a major bug in Portage. In this emergency situation, it would be allowable for a senior developer to test the fix and then roll a new release.

Before using this "escape clause," please ask yourself: is the Portage Maintainer really unavailable? Is this fix really so super-important that it gets on our Portage tree within an hour? Have you tested all of your new code to make sure that it works well? This is important! Remember that if your version of Portage is broken, it will create major problems for all our users, especially if it is unmasked. Please only use this "escape clause" when absolutely necessary -- when the consequences of not using the escape clause are too high.

And if you do, the emergency fix should be a coordinated effort among all developers currently available online (to test the new version, etc) and not be a "lone ranger" commit. There should be a post to the gentoo-core mailing list about the new "emergency" version to keep everyone in the loop and to explain why it was needed and why waiting for the Portage Maintainer wasn't an option.

The Portage Maintainer does allow certain special people to commit to the Portage development cvs tree. However, even if you are one of these people, this privilege does not entitle you to roll up new Portage releases. This is the Portage Maintainer's job. This person will review and properly QA test your changes before rolling up a new Portage release. Please allow this work to be done by the Portage Maintainer -- do not break these rules. It is our hope that this clarified policy will help to prevent future Portage QA issues.

Masked packages 

/usr/portage/profiles/package.mask contains a list of packages that should not be merged by users and comments detailing the specific reason why. Package.mask is used to prevent merging of packages that are broken, break something else, or badly need testing before going into ~ARCH KEYWORDS in the tree. When adding to package.mask, always commit package.mask prior to committing the masked ebuild. This prevents the ebuild from hitting users before the updated package.mask does.

Great care must be taken any time a package is removed from package.mask. Keep in mind that if an ebuild is in package.mask, it's there for a reason. If you didn't mask the ebuild, always contact the developer listed in the package.mask comments prior to taking any action. Additionally, if the masked ebuild is a core package, a dependency of a core package, or the unmasking has any possibility for adverse effects, the change must be discussed internally on the developer mailing list.


The purpose of ~arch is for testing new packages added to Portage.

There is a difference between using package.mask and ~arch for ebuilds. The use of ~arch denotes an ebuild requires testing. The use of package.mask denotes that the application or library itself is deemed unstable. For example, if gimp-1.2.0 is the stable release from Gimp developers, and a new bug fix release is available as 1.2.1, then a developer should mark the ebuild as ~arch for testing in portage because the release is deemed to be stable. In another example, if Gimp decides to release an unstable/development series marked as 1.3.0, then these ebuilds should be put in package.mask because the software itself is of development quality and is not recommended by the developers for distribution.

Any new package that enters Portage must be marked ~arch for the architecture(s) that this version is known to work on. The developer who commits the ebuild must verify it is in working order, and the KEYWORDS are correct.

Moving package versions from ~ARCH to ARCH 

When a package version has proved stable for sufficient time and the Gentoo maintainer of the package is confident that the upgrade will not break a regular Gentoo user's machine, then it can be moved from ~ARCH to ARCH. An indication of the package's stability would be no verified or unresolved bug report for a month after the version's introduction.

It is up to the maintainer of the package to deem which versions are stable or if development versions should be in package.mask or left in ~arch.

You must also ensure that all the dependencies of such a package version are also in ARCH.

Warning: The ~ARCH step may only be ignored if and only if the concerned package version contains a security fix or is needed to fix an important bug in the Gentoo system.

5. Variables

Required variables 

Gentoo Linux policy requires that all ebuilds contain KEYWORDS, LICENSE, and SLOT variables. HOMEPAGE, SRC_URI and DESCRIPTION should also be included except for special circumstances. DEPEND (and if necessary, RDEPEND) should be included if your package has any build or runtime dependencies, respectively.


Use DEPEND to define the dependencies required for building a particular package, and set RDEPEND to the dependencies required to run a particular package. You only need to explicitly specify RDEPEND if the ebuild's runtime dependencies are different than what you specified in DEPEND; if not specified, RDEPEND will default to your DEPEND settings. Never set RDEPEND to DEPEND yourself in an ebuild.

Code Listing 5.1

# Acceptable:
# Not acceptable:

It's also important to note that only RDEPEND dependencies are satisfied when one installs a binary .tbz2 package; use this information to help you choose the correct RDEPEND dependencies. If undefined, and ebuild's RDEPEND setting will default to DEPEND.

A package should depend upon the oldest version that satisfies the dependency. If it works with libfoo-1.2.x, don't depend on libfoo-2.x just because that's what you have installed.

In general, packages should depend on =libfoo-1.2* instead of >=libfoo-1.2. Otherwise, things may start breaking horribly when libfoo-2.0 is introduced.

Depending on a virtual package entry like virtual/foo will only work when the different packages providing virtual/foo have identical interfaces. Consider virtual/jdk-1.3 for example. Some packages don't work with ibm-jdk-1.3 while they do work with sun-jdk-1.3. For this reason, be sure that your package is tested against all virtual providers before unmasking. It may be possible to only depend on a subset of those packages in the virtual rather than the virtual itself.

6. Moving packages

Moving packages between categories 

From time to time, the Portage tree may need to be reorganized to split overflowing categories into specific smaller categories. For example, if there are a large number of firewall-related packages in net-misc, splitting those into a smaller category would be a worthwhile reorganization, whereas breaking up dev-perl would be unlikely to make sense.

This kind of decision is not something that should be made by a single developer. It should first be discussed on the internal mailing list so we can share ideas on potentially superior solutions.

Formerly, packages were moved by adding a PROVIDE line to the new ebuild that would cause the package to satisfy the DEPEND settings of ebuilds that are unaware of the package's new location. The new and correct way to move packages is to add an entry to the appropriate files in profiles/updates/ in the Portage tree. The format is as follows:

Code Listing 6.1

move net-misc/fwbuilder net-firewall/fwbuilder

In this case, we are moving the package fwbuilder from the category net-misc to net-firewall.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.
Updated October 16, 2004
Owen Stampflee
Original Author

Karl Trygve Kalleberg

Daniel Robbins

Seemant Kulleen

Jon Portnoy

Mike Frysinger

Carl Anderson

Alastaire Tse

Sven Vermeulen

Summary:  This guide is meant to be the authoritative written reference for Gentoo Linux development policy. It will be updated periodically to reflect new developer procedures.
The Gentoo Linux Store
Copyright 2001-2004 Gentoo Foundation, Inc. Questions, Comments, Corrections? Email [email protected].