Project:Portage

The Portage Development Project works to provide a continuously expanding and developing tool for the management and installation of packages. The developers work on providing a coherent system that is as trouble free as possible (backwards compatible, automated, and simple). Bugs are tracked and fixed from the Gentoo bug tracker and developer-developer correspondence is maintained on the gentoo-portage-dev mailing list. Another communication channel is the IRC channel on the Freenode network.

About Portage
Portage is a GPLv2 package management system based on ports collections. The Package Manager Specification Project (PMS) standardizes and documents the behavior of Portage so that the Gentoo packages can be managed by other package managers. Some alternative package managers for Gentoo include Paludis and pkgcore.

The goal of the Portage project is to provide a seamless integration of developer and user tools to aid the growth and maintenance of Gentoo packages. This means we work not only on Portage itself, but also on associated tools, and on ensuring that our APIs are useful to other tools.

Contributing to Portage
While there are many ways of contributing to Portage, there are two steps that are common to most of them: The bug tracker, and The source code repository. In this section we additionally cover testing Portage, and submitting patches to us.

If you want to discuss anything with us prior to contributing, or want to get in touch for some other reason, see the section.

If you want ideas on what to work on initially, check our ongoing activities subpage, which includes some low-hanging fruits for newcomers.

The bug tracker
Gentoo uses the Bugzilla bug tracking system. There is a specific Portage Development category where our bugs are filed. Here you can find tonnes of bugs to work on, and you may file your own bugs. If you want to add a new feature or discuss a change you want to make to Portage, you should file a bug here. Before opening a new bug report please make sure that the bug has not already been reported by another user!

If you are filing a bug based on a problem you found with Portage, please state the following clearly (if they are applicable):


 * How you triggered the bug (commands executed, files edited, ...).
 * What Portage version you used when you found the bug.
 * If the bug is reproducible.
 * The output of the command.

If you are looking to suggest a new feature, or discuss some changes to the way Portage works, please make sure to include the following (if applicable):


 * What the motivation for the proposed change.
 * How the proposed change fixes your tangible problem.
 * How the change affects other aspects of Portage.
 * How you think it can be implemented.

Please don't get too impatient if there is no immediate reaction to your report. Sometimes it can take a while before a developer has time to look at it (this also applies to non-Portage Gentoo bug reports). Often we'll need additional information from you while trying to resolve a bug, please provide it as soon as you can, if we have to wait too long (over a month) we'll likely close the bug as RESOLVED:NEEDINFO, you can however reopen it when you posted the requested information.

Please do not reopen bugs unless you're in one of the following situations:


 * The bug was marked as RESOLVED:FIXED, but you can still reproduce it with the new version that is supposed to contain the fix (the version is generally stated when the bug is closed).
 * The bug was marked as RESOLVED:NEEDINFO and you have provided the requested information.
 * The bug was marked as RESOLVED:WONTFIX, RESOLVED:CANTFIX, or RESOLVED:LATER and you think we misunderstood you.

Do not reopen a bug just because you disagree with our resolution.

Be aware that we will still read comments on bug reports even if the report itself is closed, so you don't have to reopen it just to get our attention.

Every bug report deals with one specific problem, please respect that and don't talk about other not directly related issues on a bug report. If you want to discuss a big change to Portage, try first to think about how you can divide the problem into smaller problems in order to file small self-contained reports that can be dealt with independently.

The source code repository
The Portage source code is maintained within a git repository on Gentoo's gitweb. If you are a dev: The main repository is located at git+ssh://git@git.gentoo.org/proj/portage.git, please note that it is subject to strict access controls, only people listed in the developers section on this page are able to commit to it.

For anonymous access please use our anongit. There is also a non-HTTPS anongit should you need it.

We also have a GitHub mirror, but note that this is just a mirror, so do not file bugs nor pull requests there.

The repository currently contains the following branches (incomplete list):


 * master: the current main development line
 * repoman: repoman rewrite
 * infra: branch used by the infra team for hotfixes

Testing Portage
We use unit tests for Portage. The details are documented in TEST-NOTES, and to run them you use the runtests script. You should always make sure that your changes do not introduce any regressions, and the testsuite will help you catch regressions. To make sure there are no regressions on your code in the future, you should write tests for your own code too.

As of version 2.1.2 of Portage, it is also possible to test multiple versions of Portage. There are various reasons why you'd want to have multiple versions of Portage available at the same time without having to install them as system default. Examples would be to check which versions are affected by a specific bug, to test new features before deploying a new version or have a git checkout available for testing while keeping a stable release for normal operation.

You can have and use an arbitrary number of Portage installations parallel to each other by adjusting the two environment variables PATH and PYTHONPATH. For example if you have a checkout of the master branch at you'd set them like this:

With those settings calling tools like, , or will pickup the correct locations to import libraries. External tools like gentoolkit or porthole may or may not respect those settings. Setting PATH variable is not necessary if the commands are called by their full name (e.g. instead of ).

Submitting patches
In order to submit patches, there are a few criteria you'll need to follow. Don't worry, most of them are fairly obvious and simple practical things. The criteria for Portage are documented extensively in our DEVELOPING guide. (If you are contributing to something else than Portage, make sure to check if that project has a similar guide.) Here are some highlights:


 * Use tabs.
 * Cap line width at 80.
 * Use if foo is not None rather than if foo != None".
 * Avoid has_key.
 * Use raise KeyError("No Key) instead of raise KeyError, "No key".
 * Use one import per line.
 * Python docstrings should conform to the Portage Docstring Specification.

If you make a significant change (e.g. fix a bug), add it to RELEASE-NOTE per that format. If the change is a massive new feature or very important bug fix, also add it to NEWS per that format.

When submitting your changes, you should preferably use git. This is a breeze if you already know git. Make sure your changes are split up into small specific commits with descriptive commit messages that describe what you are changing and why (see DEVELOPING for format details), and just to.

If you don't know how to use git, see Submitting patches without git.

Submitting patches without git
If you don't know git, you really should learn at least the basics of git... Try reading the comprehensive yet accessible Pro Git book.

If the patch should somehow be so important that we need it right away, before you have time to learn git, you can try sending an email to to which you attach unified diffs. A diff is a file that only contains the changes you've made (and some context), rather than the entire file you have changed something in. You can make unified diffs using. Also include a detailed explanation of what the changes are in the email. Always state against which version or revision and branch the patch was made, as we can't always figure this out for ourself when you haven't used git.

If the patch is related to a specific bug report, please attach it there as text/plain. If it is not directly related to a bug report (to your knowledge) please send it to the mailing list and tag the subject with '[PATCH]'.

Current development activities
We have a subpage dedicated to current activites, which includes some low-hanging fruits for newcomers. We also keep a proposals subpage for big ideas.

Two major activities at the moment include:


 * A repoman rewrite
 * A new plug-in sync system

Getting in touch
We have a mailing list we use for for patch submissions and review before it will be included in the main code base. This list is also used for discussion about new directions and features, and just about everything else.

You must be a list subscriber to send to this list. Please see the Gentoo mailing lists page for how to subscribe. The address of our list is:.

In addition to the mailing list, we have an IRC channel on Freenode:. This can be used if you want a more synchronous conversation. If nobody's answering, please be patient. If you feel it is urgent, you can try pinging the team lead, bernalex.

Portage project members
Being a Gentoo developer is a formal requirement to being a Portage project member. The members are listed in the info bar up to the right. However, in addition to the formal members, we have some equally valued contributing members which are not Gentoo developers.

See the membership subpage for how to become a Portage project member. Of course, you can become a Gentoo developer too.

Here is the list of contributing non-Gentoo members:

Subpages

 * Project:Portage/Ongoing-TODO
 * Project:Portage/Repoman-TODO
 * Project:Portage/Repoman-Module-specs
 * Project:Portage/Proposals
 * Project:Portage/Meetings
 * Portage plug-in sync system specification
 * Repository Verification
 * Changed Deps
 * Portage Frequently Asked Questions (FAQ)
 * List of common major Portage problems and solutions
 * Guide for manually fixing a broken portage install
 * Membership policies of the Portage project

Documentation resources
The following resources are maintained by the Handbook and the Devmanual projects respectively. Since they are the primary online documentation for Portage they will be listed here:

Handbook project

 * A Portage Introduction
 * Portage Features
 * Working with Portage
 * USE flags

Devmanual project

 * Developer Handbook - Deprecated. Formerly maintained by the Community Relations project.
 * Gentoo Devmanual - Maintained the Devmanual project, a child project of the QA project.

External resources

 * Travis-CI.org Portage testing (Travis CI).
 * Portage docstring-spec
 * Bugzilla policies
 * Release policies
 * Portage documentation (generated from docbook)
 * Portage API documentation (generated with epydoc)
 * Portage NEWS file (lists new features)
 * Portage RELEASE-NOTES file (lists upgrade information)
 * The IRC channel on Freenode.
 * gentoo-portage-dev mailing list
 * package
 * Portage GIT repository mirror (GitHub mirror)
 * Open bugs assigned to the dev-portage alias
 * Open bugs assigned to the pms-bugs alias
 * Open bugs assigned to the tools-portage alias