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:
  • http://cvs.mandrakesoft.com/cgi-bin/cvsweb.cgi/SPECS/
  • http://www.debian.org/distrib/packages
• 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 

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 http://www.gentoo.org/proj/en/devrel/copyright-assignment.xml.

fPIC 

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 http://www.gentoo.org/proj/en/hardened/pic-internals.xml.

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.

Perl 

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:

pkg-ver{_suf{#}}{-r#}.ebuild

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:

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.

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.

Virtuals 

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:

PROVIDE="virtual/cron"

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:

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.

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:

# 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:

# $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 

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.

~ARCH in KEYWORDS 

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.

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.

DEPEND and RDEPEND 

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.

# Acceptable:
RDEPEND="${DEPEND}
	net-ftp/curl
	virtual/glibc"
# Not acceptable:
RDEPEND="${DEPEND}"

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:

move net-misc/fwbuilder net-firewall/fwbuilder

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