Gentoo Developer Handbook

Sven Vermeulen  Author
Seemant Kulleen  Author
Shyam Mani  Author
Karl Trygve Kalleberg  Author
Mike Frysinger  Author
Alastair Tse  Author
Paul De Vrieze  Author
Nicholas D. Wolfwood  Author
Marius Mauch  Author
Daniel Black  Author
Wernfried Haas  Author
Chrissy Fullam  Author
Łukasz Damentko  Author
Daniel Robbins (Retired)  Author
Markos Chandras  Author
John P. Davis (Retired)  Author
Tim Yamin (Retired)  Author
Jorge Paulo (Retired)  Author
Zack Gilburd (Retired)  Author
Benny Chuang (Retired)  Author
Erwin (Retired)  Author
Jon Portnoy (Retired)  Author
Carl Anderson (Retired)  Author
Donny Davies (Retired)  Author
Peter Gavin (Retired)  Author
Dan Armak (Retired)  Author
Owen Stampflee  Author
Ciaran McCreesh (Retired)  Author

Page updated October 31, 2013


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

Note: The Gentoo Recruiters reserve the right to assign a developer a new mentor if the initial mentor is idle to queries about the new developer or if the mentor files the bug but then does not assist the new developer through the rest of the process.

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.

A number of quizzes are offered. Please read the page carefully to understand which one you need to complete. If unsure, ask your mentor. In general, 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 and end of mentoring quizzes.

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. 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 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 for more details.

3.g. Mail

All developers are provided with a mail address for Gentoo use.

Please see 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 - 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 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.

Code Listing 11.1: When going away

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

Code Listing 11.2: When coming back

$ 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


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.


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

Code Listing 1.1: ~/.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.

Code Listing 1.2: Checking out gentoo-x86

$ cvs -d 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:

Code Listing 1.3: Updating in gentoo-x86

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

Code Listing 1.4: Checking out portage

$ svn co svn+ssh://

Updating Portage

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

Code Listing 1.5: Configuring repos.conf for use with CVS

main-repo = gentoo

location = /home/username/gentoo-x86
sync-type = cvs
sync-uri =
sync-cvs-repo = gentoo-x86

Note: Due to the fact that the cvs checkout has no metadata cache, your portage may become really slow

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:

Code Listing 1.6: Adding a package

(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?

Code Listing 1.7: Removing old versions

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


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 ( can help you.

Code Listing 1.8: Using repoman

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

Code Listing 1.9: ~/.ssh/config

  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. contains instructions on configuring your mail.

Developers have access to webhosting,$YOURNAME. Please see the Webspace Configuration Guide for details.

5. Developer hierarchy

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

Global issues will be decided by an elected Gentoo council.

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


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:

Important: If the project you want to contribute to as a staff member isn't on this list and you think it should, please contact Developer Relations about policy change.

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 mail address, ssh access to (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.

Note: As a staff member who isn't going to work on ebuilds, you won't be asked technical questions about them. All that will be required from you at this stage of your recruitment is a good understanding of Gentoo internals.

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. Etiquette policy

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

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

1.c. Tips