Gentoo Developer Handbook

Content:

• Introduction
  This part covers aspects which apply to most areas of Gentoo development. This section is only really relevant if you are a Gentoo developer; otherwise you should skip this.
  1. Introduction
     This section outlines the purpose of the Gentoo Developer Handbook.
  2. Becoming a developer
     This section aims to explain how one can become a Gentoo developer.
  3. What you get
     This section outlines what services are available to Gentoo developers.
  4. Help for new developers
     This section provides help and instructions for new developers.
  5. Developer hierarchy
     This section outlines the hierarchy of Gentoo Developers and development.
  6. Staff member policy
     This section outlines recruitment and retirement policies for Gentoo staff members.
• Policies
  This part covers the different policies which we expect developers to abide when committing items to CVS.
  1. Ebuild policy
     This section outlines the ebuild policy which every ebuild in Portage must follow.
  2. Etiquette policy
     This section outlines the etiquette policy for Gentoo developers.

A. Introduction

1. Introduction

1.a. Introduction

The aim of this handbook is to outline Gentoo development policies, and make you, the developer, informed of policies, standards and procedures which Gentoo considers to be core values of our development system.

This handbook is not intended to be the universal guide to everything - the opportunities open to you are endless, and as a result, this handbook is designed to teach you the principles which we think make up a good Gentoo developer - the rest is up to you!

If you are new to Gentoo development or even an old veteran and are at any stage unsure about anything, feel free to ask the gentoo-dev mailing list, or #gentoo-dev.

1.b. Requirements

Before you start to tinker, it is important to have a working Gentoo installation, both for documentation and development purposes, and we also recommend that you have a good knowledge of topics covered in the ``Working with Gentoo'' section in the User Handbook to help you with your development work.

Most of this guide is targeted at developers, but, if you are just interested to see what makes Gentoo development work, this guide may provide some valuable insights.

The best way to get noticed [ and to possibly become a Gentoo developer! ] is to file intuitive and accurate bug reports at the Gentoo Bugzilla, with patches if possible, and to help us out with what you think would make a better Gentoo for everyone whether by providing patches for new features, submitting new ebuilds, or solving issues with existing ones.

2. Becoming a developer

2.a. Introduction

There are many ways to become a Gentoo developer, which this section discusses. There are also various steps that new "recruits" have to go through before they become official developers.

2.b. Helping out

Firstly; to be asked to become a developer you should either apply to an opening, or just help out whether in the form of user support or filing bug reports - we notice frequent contributors making contributions to Gentoo and we attempt to reward them by giving them the chance to become a Gentoo developer. Gentoo has many paths, and the Gentoo Developer Relations Recruitment Team is always looking out not just for developers - documentation writers and infrastructure maintainers are just as important too for our distribution to run smoothly.

You should look out for openings for developers in the GMN, as well as the /topic of #gentoo-bugs on irc.freenode.net - if you feel you could fill in one of those positions, try to find a mentor who is willing to sponsor you, or contact the Gentoo Recruiters who may be able to find a mentor for you. Please do not file "New Developer" bugs on yourself since this task is designated for the mentor and any such bugs will be closed.

2.c. Mentoring

All new developers must have a mentor, who is an existing Gentoo developer responsible for guiding a new developer as well as offering to help the developer later after the developer has passed through the recruitment process.

A mentor should assist you by helping you with any questions you might have, as well as outlining your Gentoo responsibilities, especially those in relation to what you would initially work on.

Once a developer agrees to mentor a new developer, the mentor should file a bug and assign it to the Gentoo Recruiters - the Gentoo Recruiters page explains in detail what information should be filed.

2.d. Waiting

All new developers pass through a waiting period of up to a month, depending on how ready the mentor thinks the developer is as well as feedback from any other related staff. During this time, the new developer should complete the quiz which would be reviewed by the developer's mentor and the Gentoo Recruiters to ensure that the developer is "ready". In special cases, the waiting period is determined by the Recruiters and/or Gentoo Developer Relations leads.

Two quizzes are offered: the ebuild quiz, and the staff quiz. Developers who will be working purely on infrastructure, GLSAs or other non-ebuild areas should take the staff quiz, any developers who require commit access to the Portage tree should take the ebuild quiz.

Once a new developer has completed the quiz, the developer should send it off to the mentor who is responsible for reviewing it in conjunction with the Gentoo Recruiters. If the quiz answers are deemed to be of a sufficient standard, then the recruitment process would continue. Otherwise, a new developer can redo the quiz again, providing that it is completed in the waiting period.

Additionally, new developers should be responsive to any members of the Recruiters Team who have any questions - any developers who do not reply promptly will have their "New Developer" bug closed, which would only be reopened at the discretion of the Gentoo Recruiters.

2.e. Jumping the gap

After your mentor and the Gentoo Recruiters have reviewed your quiz and deemed it to be of a suitable standard, you should send it along with a public SSH2 DSA key (e.g. id_dsa.pub) to the Gentoo Recruiters. If the Recruiters consider your quiz to be of a satisfactory standard, they will set you up with the services that you require.

After this time, you enter a "probationary period" of 30 days during which your mentor is responsible for your actions, providing accountability - also, Gentoo Recruiters may reject new developers during this time if they feel it is appropriate.

3. What you get

3.a. Introduction

Gentoo provides developers with all the necessary services which they might need for their development efforts. If you require anything else, please do not hesitate to contact the Infrastructure Team!

Once you are an authorized developer, your recruiter should organize the following services. If you experience any problems, please see your recruiter or the mentioned staff with access to the required service.

3.b. Bugzilla

Developers are able to change all aspects of bugs in Bugzilla. If you have an existing account the email address should be changed to your Gentoo address by a Bugzilla administrator.

3.c. CVS

Not all developers receive CVS access - if you require Portage access to the gentoo, gentoo-projects, or gentoo-x86 tree get someone on the recruiters team to do this for you. You may need to justify your need for this to happen, however.

3.d. IRC

When you are a developer, you will receive a gentoo/developer/* cloak signifying that you are a developer. If you do not, please contact recruiters or ask on the #gentoo-groupcontacts channel. Please be aware that Freenode cloaks may neither contain underscores (_) nor dots (.) in the last part, so you must either choose an appropriate nickname or a differing cloak.

Along with that you get operator status on #gentoo-dev. Additionally, team leads may decide to give you operator status on specialized channels such as #gentoo-hardened, for example. Abuse of operator powers on #gentoo-dev may lead to your operator powers being removed instantly along with the possible removal of your developership. If you are given operator powers, we ask that you use them constructively to benefit everybody when either developers or users break up the cleanliness of the channels.

The #gentoo IRC channel is no longer controlled by Developer Relations, but by the gentoo-ops project. Operator status in #gentoo does not in any way signify that the user is a developer.

"Special" Gentoo channels such as #gentoo-hardened and #gentoo-server are given to people at the discretion of the team - in this case, the hardened and server teams.

IRC Channels are owned by their relevant project leads, whether strategical or operational and the owner has the discretion of voicing or unvoicing members of the public. If you believe that those powers are being abused or are being used with wrong considerations; then speak to the Gentoo Linux Developer Relations team.

3.e. Forums [Optional]

Ask one of the forums administrators in #gentoo-forums or forum-mods@gentoo.org to update your forum status on the Gentoo Forums, if needed. Forum accounts are not mandatory.

3.f. Planet [Optional]

Developers who have a personal blog can request to be added to the planet aggregator. The planet software creates a custom feed of all developer's blog posts, separated into two categories: on-topic (Gentoo and computer related content) on Planet Gentoo, and all topics on Gentoo Universe.

Also, if a user does not already have a blog, we host our own blogging software and can create an account for you.

Please see http://www.gentoo.org/proj/en/userrel/planet/index.xml for more details.

3.g. Mail

All developers are provided with a developer@gentoo.org mail address for Gentoo use.

Please see http://www.gentoo.org/proj/en/infrastructure/dev-email.xml for more details.

3.h. Mailing lists

All developers must be subscribed to the gentoo-core and gentoo-dev-announce mailing lists. All developers should be subscribed to gentoo-dev and gentoo-project, though neither are developer requirements. Contact someone on the Recruiters team to subscribe you to the above mailing lists or if you are having difficulties.

gentoo-core is to be used for internal discussions; technical discussions should be discussed on gentoo-dev; non-technical discussions should be discussed on gentoo-project; while gentoo-dev-announce is for announcements only. If you send a message to dev-announce, you should manually cross-post to an on topic mailing list and set reply-to there.

If you are subscribed on any other Gentoo mailing lists, you should unsubscribe and resubscribe with your new mail address.

3.i. Shell access

Developers currently get a shell account on dev.gentoo.org - this provides mail storage, SMTP relaying and also an IRC tunnel for developers to use to access freenode.

To ensure security, access is only available through SSH keys, which your mentor should place on your account and allow you to log in: please see http://www.gentoo.org/proj/en/infrastructure/cvs-sshkeys.xml for more details regarding SSH keys..

3.j. Service usage policies

Services provided by Gentoo should only be used for Gentoo development work. Infrastructure has the right to disable any accounts which are a security risk, these include inactive accounts which will be suspended by the infrastructure team if you are presumed idle, and your IRC #gentoo-dev status would also be voiced.

If any files in your account are found to be harmful towards other developers or users on the box, or pose a risk to the Gentoo project (such as illegal .torrents), Gentoo Infrastructure will suspend your account which would only be unlocked after investigation from Gentoo Developer Relations. In most cases, your developership may be suspended if such files are found. The same policies also apply to Gentoo CVS and other Gentoo-provided services you may be offered.

3.k. Activity policies

Gentoo understands that as life changes, so may your availability. We respectfully request that if you know you will be unavailable for an extended period of time (vacation, big project at work, family needs, etc) that you utilize the devaway system.

on dev.gentoo.org
$ echo "Away until 2007-08-30, contact $dev1 in my absence" > ~/.away

on dev.gentoo.org
$ rm ~/.away

In the on going effort to keep our developer pool up-to-date and our resources secure, Developer Relations periodically reviews developer activity in the search for inactive developers. A developer is considered inactive if no contributions are made over a period of 60 days. Activity is determined by CVS commits, bugzilla statistics, and peer feedback. Not everyone's activities are so easily traced, as such, Developer Relations often requests feedback from a project lead or team members of a developer suspected to be inactive.

Any developer suspected to be inactive for a period in excess of 60 days may be subject to retirement. Developer Relations will first research and assess the situation, attempt to contact the developer, or if attempts are unsuccessful may chose to retire the developer. Please note that if you are in devaway for more than 60 days, you may also be considered inactive, however, return dates will be taken into consideration. If you are retired due to inactivity and wish to return, you need only contact Recruiters to begin the recruitment process again.

4. Help for new developers

4.a. Using CVS

Introduction

This guide is not intended to be a manual on using CVS; for that, take a look at the CVS info page or /doc/en/cvs-tutorial.xml. Instead, this guide focuses specifically on using CVS and Repoman in Gentoo's ebuild tree.

Configuration

Typically, you'll want something along these lines in your ~/.cvsrc:

cvs -q -z0
diff -u -B
checkout -P
update -d -P

Finally, many people using CVS like to use compression (-z#). We ask that developers who are not on dialup connections please use -z0 - with the contents of our CVS repository and the load on our CVS server, you actually experience a speed increase without compression.

Checking out from CVS/SVN

There are a few useful modules in Gentoo's CVS repository. Ebuilds are kept in the gentoo-x86 module. gentoo contains the XML for the website, documentation, developer directories, developer pictures, and so on. gentoo-projects contains various projects and generally replaces the gentoo-src cvs module. gentoo-src is kept around for history, please transition to a different cvs module if you are still using it.

$ cvs -d username@cvs.gentoo.org:/var/cvsroot co gentoo-x86

Before working in the tree at any time, it's always a good idea to do an update to check for changes and prevent conflicts. You can update in any subdirectory of the tree if you don't want to wait for a tree-wide update, but from time to time it's a good idea to update your entire tree:

$ cd gentoo-x86
$ cvs update

Gentoo also offers subversion services for those who prefer SVN over CVS. Many core projects such as portage and baselayout are hosted here now.

$ svn co svn+ssh://username@cvs.gentoo.org/var/svnroot/portage

Updating Portage

If you want to use CVS as your primary Portage tree, you can add the following lines to /etc/make.conf, replacing you with your username:

SYNC="cvs://you@cvs.gentoo.org:/var/cvsroot"
CVSROOT=":ext:you@cvs.gentoo.org:/var/cvsroot"

On supported architectures, you should also have sandbox in your FEATURES to ensure ebuilds do not modify the root filesystem directly.

Adding/Removing packages

Say you're ready to add a brand new package, foo, in app-misc:

(Replace CVSROOT with the location of your checked-out CVS tree.)
$ cd $CVSROOT/app-misc
(Always update before working in part of the CVS tree!)
$ cvs update
$ mkdir foo
(Here, we add the package directory foo to the CVS repository.)
$ cvs add foo
$ cd foo
(It's better to keep in-progress ebuilds in an overlay outside of your CVS tree.)
$ cp /path/to/foo-1.0.ebuild ./
$ repoman manifest
$ ${EDITOR} metadata.xml
You don't necessarily need a files directory any more
$ cvs add foo-1.0.ebuild metadata.xml files
[Don't forget to create a ChangeLog - see the man page for echangelog.]
$ echangelog "New ebuild for foo. Ebuild written by me. Fixes bug #XXXXXX."

See the Gentoo Metadata section for more information on metadata.xml.

At this point, you're ready to commit (see the section on Commits below). But what if you want to remove foo-1.0 when foo-1.1 is out?

$ cd $CVSROOT/app-misc/foo
$ cvs update
$ cvs remove -f foo-1.0.ebuild

And now you're ready to commit (see the section on Commits below).

Commits

Always use repoman commit rather than cvs commit. Repoman is a quality assurance (QA) tool that performs basic checks and creates Manifests. If any part of repoman's output is unclear, please see man repoman. Additionally, you may tire of entering your key passphrase repeatedly; keychain (http://www.gentoo.org/doc/en/keychain-guide.xml) can help you.

[Make sure there are no root-owned files present prior to running repoman!]
("scan" scans the current directory for QA issues. "full" is more complete.)
$ repoman scan
("commit" does a scan, then commits, while also updating the Manifest. Make sure you
 add a verbose and useful CVS ChangeLog message...)
$ repoman commit

Speeding CVS up

If you have noticable high ping times to the cvs server, you might want to use the ssh master slave setup where you only connect to the other ssh server once and let it do the next commands over that connection. This way you save the handshake overhead which may speed up the whole checkout/commit by factor 3. Just add the code snippet given below to your config.

Host cvs.gentoo.org
  ControlMaster auto
  ControlPath ~/.ssh/master-%r@%h:%p
  ControlPersist 3600

4.b. Miscellaneous

Putting files on mirrors

Distfiles are automatically fetched by the Gentoo Mirror System. You only need to monitor your distfiles for fetch errors. Please see the Distfiles Overview Guide for comprehensive instructions.

Mail and Web

Our infrastructure allows developers to manage their own mail. http://www.gentoo.org/proj/en/infrastructure/dev-email.xml contains instructions on configuring your @gentoo.org mail.

Developers have access to webhosting, http://dev.gentoo.org/~$YOURNAME. Please see the Webspace Configuration Guide for details.

5. Developer hierarchy

4.a. Introduction

This section aims to explain the Gentoo development hierarchy and gives developers an insight to how Gentoo Linux development management is structured.

5.b. A short history of Gentoo's management structure

The first attempt to come up with a management structure to solve problems with coordination and communication issues was made in 2003 with the structure described in GLEP 4. As Gentoo grew larger over the time, some problems with the management structure were discovered and a new one was needed to solve these issues. GLEP 39 describes both the reasons behind this as well as the outcome of the discussion.

5.c. Current Management structure according to GLEP 39

A project is a group of developers working towards a goal (or a set of goals).

• A project exists if it has a web page at www.gentoo.org/proj/en/<project name> that is maintained. ("Maintained" means that the information on the page is factually correct and not out-of-date.) If the webpage isn't maintained, it is presumed dead.
• It may have one or many leads, and the leads are selected by the members of the project. This selection must occur at least once every 12 months and may occur at any time.
• It may have zero or more sub-projects. Sub-projects are just projects that provide some additional structure, and their web pages are in the project's space.
• Not everything (or everyone) needs a project.
• Projects need not be long-term.
• Projects may well conflict with other projects. That's okay.
• Any dev may create a new project just by creating a new page (or, more realistically, directory and page) in gentoo/xml/htdocs/proj/en and announcing it on the gentoo-dev-announce mailing list.

Global issues will be decided by an elected Gentoo council.

• There will be a set number of council members. (For the first election that number was set to 7 by acclamation.)
• Council members will be chosen by a general election of all devs once per year.
• The council must hold an open meeting at least once per month.
• Council decisions are by majority vote of those who show up (or their proxies).
• If a council member (or their appointed proxy) fails to show up for two consecutive meetings, they are marked as a slacker.
• If a council member who has been marked a slacker misses any further meeting (or their appointed proxy doesn't show up), they lose their position and a new election is held to replace that person. The newly elected council member gets a 'reduced' term so that the yearly elections still elect a full group.
• Council members who have previously been booted for excessive slacking may stand for future elections, including the election for their replacement. They should, however, justify their reasons for slacking and should expect to have it pointed out if they don't do so themselves.
• The 'slacker' marker is reset when a member is elected.
• If any meeting has less than 50% attendance by council members, a new election for all places must be held within a month. The 'one year' is then reset from that point.
• Disciplinary actions may be appealed to the council.
• A proxy must not be an existing council member, and any single person may not be a proxy for more than one council member at any given meeting.

5.d. Consequences of Gentoo's management structure

As a consequence of the new management structure, global decisions will be made by the elected council. This should give Gentoo a general direction - smaller issues affecting only a project or two should be decided inside the projects involved, probably with input from other developers. The council should be a fair representation of the developer base as every developer is able to vote, so interests should be represented in a fair way. If the council does a bad job and the developer base is unhappy with its work, the council can be voted out.

Decisions within a project can be made by the people inside the project itself, of course coordination between the projects is necessary. The (sub-)project leads are usually responsible for doing this.

Most projects have an Operational and Strategic lead, but basically it is up to the project what positions are created and how they are called - this also applies to sub-projects.

Some projects appoint a contact person for communication to another project e.g. a developer within the forums project who is responsible for communication with the infrastracture project.

All in all, the current structure has no clear list of responsibilities the project leads are supposed to satisfy. They are chosen by the members of the project, the practical responsibility of a lead is "whatever the members require", and if that isn't satisfied, the members can get a new lead (if they can find somebody to take the job!).

6. Staff member policy

6.a. Gentoo Staff Member policy

Introduction

Running a Linux distribution has multiple aspects and many of them aren't directly connected to coding. Every distribution needs people to run its servers, help its community, provide documentation, handle project's finances and legal issues and serve many other tasks. Their contributions are as important as code contributions. These developers are called staff members in Gentoo.

Types of staff members

The following list contains all types of staff members we are currently recruiting in Gentoo:

• Gentoo Infrastructure project members
• Gentoo Documentation editors and translators
• Gentoo Monthly Newsletter editors and translators
• Gentoo Forums global moderators and administrators
• Gentoo Developer Relations members
• Gentoo User Relations members
• Gentoo Public Relations members
• Gentoo Security GLSA coordinators
• Gentoo Sunrise developers
• Gentoo Foundation officers

How is staff member access different from ebuild developer access?

Access is assigned based on the responsibilities of the Staff Member. All Gentoo Developers are provided with an gentoo.org mail address, ssh access to dev.gentoo.org (for shell, ldap, public_html, etc) as well as cvs access to gentoo's web/project pages. As a staff member you will not be granted access to the ebuild tree, as ebuild developers are, but may be granted access to other area's based on your need and responsibilities.

How can I become a Gentoo staff member?

You have to work with members of the project you wish to help. You are invited to the team when your level of contributions and expertise justify you becoming a developer in that project. It may take time and may also require passing internal recruitment procedures within that project first. Those procedures are in place to ensure you know what your future function within Gentoo involves, they are created and maintained by the project itself.

When you are ready, you will need to look for a mentor and a developer bug will be filed for you after your mentor has approved your staff quiz. Once a recruiter has been assigned to your developer bug, both of you will need to schedule your review. Please see the mentoring guide for more information.

I would like to be recruited as a staff member but also plan joining other projects in future

Every Gentoo developer can join any project (s)he wishes if developers of the project agree with that. Before you can start contributing to the ebuild tree though, you will have to apply for ebuild developer recruitment. This means you need a mentor, a history of technical contributions (bug fixes, overlays, etc...) and adequate training. Please contact recruiters about this.

How is retirement handled for staff members?

You have to either remain active within the project you have joined or move to other projects. If there are no projects within Gentoo you're active in, you are subject for retirement via Gentoo Undertakers procedures.

B. Policies

1. Ebuild policy

1.a. 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:
  • Debian
  • Mandriva
  • Fedora
• 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.

1.b. Specific guidelines

fPIC

On some architectures, shared libraries must be built with -fPIC. On x86 and others, shared libraries may build without -fPIC. This can 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 shared libraries with -fPIC. More information on PIC is available at http://www.gentoo.org/proj/en/hardened/pic-internals.xml. If you are unsure, please ask in a public developer forum (like the gentoo-dev mailing list or #gentoo-dev irc channel) for help.

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.

1.c. Ebuild policy

Naming policy

Ebuild file names consist of four logical subsections:

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

The first subsection, 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 and gtk+. We have some packages in Portage that don't follow these rules, but your packages should.

The second subsection, 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 subsection, {_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 subsection of the package name is the Gentoo Linux-specific revision number ({-r#}). This subsection, 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.

Scope

Whenever an ebuild is sourced, the functions and variables within it are loaded into memory by the script interpreter. However, only variables and instructions that are not part of a function are interpreted - functions such as src_compile() are only executed by Portage when the ebuild has reached the compile stage.

The code within these functions are considered in "local scope" while everything outside of the functions is in the "global scope" meaning they are executed every time the ebuild is sourced.

An external application (such as grep, sed or awk) should never be called in global scope for performance reasons, and alternatives such as using built-in bash replacement should be used instead. Useful alternatives can be found in the Advanced Bash Scripting Guide.

Additionally, any external application that may be called in global scope can not be guaranteed to exist on the system. If the command is placed in local scope (for example, in the pkg_setup() function), we can guarantee its presence by placing it in the ebuild's ${DEPEND}.

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 <me@me.com>

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.

1.d. QA policy

Portage / baselayout release policy

Only members of the Portage team (who know who they are) have the authority to release new releases of Portage. No one else is allowed to roll new releases of Portage.

Only members of the baselayout team (who know who they are) have the authority to release new releases of baselayout. No one else is allowed to roll new releases of baselayout.

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.

1.e. 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. RDEPEND should be set explicitly, even if RDEPEND=${DEPEND}.

RDEPEND="${DEPEND}
	net-ftp/curl"

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.

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.

2. Etiquette policy

2.a. Introduction and some simple suggestions

These suggestions are designed to be an easy-to-follow guide to what Developer Relations would expect to be good developer etiquette. They should cover most areas and should be employed wherever they can be.

That doesn't mean that we expect you to follow this guide to the bullet point; nor do we expect you even agree with it - we do expect, however that all developers maintain reasonable standards of behaviour with our community - whether to other developers or users. However, you may be subject to sanctions or a suspension if a reasonable standard is not met.

By reasonable standards we don't want you to feel that we are not allowing you to say anything, rather, we believe that how you say it, and the method and professionalism in how you express your opinion defines whether you meet the reasonable standards or not, since, as a developer, what you say and do reflects upon Gentoo and the project as a whole. We just require you to be equally respectful to developers and users alike, and to value the opinion of everybody - even if you think it's totally wrong.

You should try to use good spelling and grammar everywhere: whether in a CVS commit message, a ChangeLog, or even on IRC if you want to be really nice and make somebody's day. But don't worry; we won't really mind if you don't. You might not notice it, but by taking some effort to clean things up, the amount of time it takes to read your sentences is greatly lowered. However, it is also important not to lose the rope at the same time and make something too eloquent that takes too long to parse.

2.b. What you should try not to do

One should try to not be rude, abusive or impolite under any circumstances. Sometimes, just one sarcastic comment can change the tone to the reader. If you think you might give somebody a bad as a result of your comment, and if you really need to say it, make sure people understand that you are not trying to be offensive.

Please remember that you are an official representative of Gentoo. In this capacity, you are expected to maintain a certain level of professionalism and courtesy in your day-to-day interactions with users and other developers.

2.c. Tips

ChangeLogs

• Make your ChangeLogs readable to the average end-user: try to keep things simple and short if you can, but provide any critical information as needed. Remember that ChangeLogs need to be written in good, "correct" English even if they are short. Punctuation is essential.
• Please don't use "Gentooified" language, except for accepted terms such as "ebuild" and "version bump". If you are being verbose, please use the correct punctuation and quote marks.

• Any function names should be encapsulated in quotation marks or speech marks.
• Be verbose: "Version bump." is good, however "Version bump; see bug #..." is even better. This not only helps users, but it also helps other developers as well.
• Don't use phrases such as "Tested for months, should work." or "I think this should fix the problems." as something either does its job or it doesn't. It is much better to inform users to test your package thoroughly and to report any bugs to you.
• When referring to ebuild sections such as the homepage variable, use "HOMEPAGE" remembering to add the quotes and to use the correct case. This makes things a bit more precise, namely telling the reader that you changed the variable; rather than the homepage your package might go to when it starts up, for example.
• When using acronyms, please use the proper cases. For example, "ALSA", not "alsa", "Win4Lin" not "win4lin".

Ebuilds

• Respect developers' coding preferences. Unnecessarily changing the syntax of an ebuild increases the load on the CVS server and can cause complications for others. Syntax changes should only be done if there is a real benefit, such as faster compilation, improved information for the end user, or compliance to Gentoo policies.

IRC

• Be nice and respectful of everybody - even if they are bombarding you with messages.
• Do not abuse or discriminate users or developers - whether as a joke or as sarcasm.
• Answer any questions to the best of your knowledge - it is best that you do not answer what you don't know to avoid confusion. There is no policy on any collateral damage caused by developers to users however: if the developer did any contact such as SSHing into a users' box, the developer would be held accountable for any issues arising out of the same. As a result, we don't really recommend it.
• If you are a developer with operator powers, you must not abuse them - if you have a disagreement with a user resolve the issue peacefully and do not resort to kicking them or even kickbanning them unless the situation is really severe and other developers approve of critical measures.
• #gentoo and #gentoo-dev are clean-language channels; other #gentoo- channels have policies set by their respective channel owners. Because the majority of traffic on #gentoo-dev is from Gentoo developers, people perceive this channel as officially representing Gentoo. In order for us to present Gentoo in a professional manner, we request that developers keep #gentoo-dev a 'clean-language' channel.

Forums

• Be nice and respectful of everybody - even if they are asking the most unimaginable questions. Either voice your opinion courteously, or voice no opinion.
• Follow the forum rules and try keeping to the discussion rather than veering off course.
• Try to be active in development. If users are asking why something was added, please explain it. If users are asking why something is missing, explain that. Use your knowledge and help out if you can. At the same time, if you don't know, don't confuse people.

Mail

• Be nice and respectful of everybody. Don't respond to personal attacks with more attacks. Either voice your opinion courteously, or voice no opinion.
• Don't use HTML mail - it can cause annoyances - and it is recommended that you use a word-wrapping mail client if sending out plain text messages. Some people also block HTML mail which may cause correspondence problems.
• When replying to user or developer mail, be both courteous and don't simply refer the user along to another developer - try to explain why things are as they are if you can. An example of good, well thought reply goes along the lines of: "I am referring you to <insert name here> as <person> is now the maintainer of the package. Any further issues should be addressed to <person>. Sorry for any inconvenience."

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.