Project:Portage

From Gentoo Wiki
Jump to:navigation Jump to:search
Portage
Description The Portage Development Project is devoted to maintaining and updating Portages core functionality and utilities.
Project email dev-portage@gentoo.org
Packages p.g.o/dev-portage@gentoo.org
Code repository https://gitweb.gentoo.org/proj/portage.git/
Mailing list gentoo-portage-dev@lists.gentoo.org (archive)
IRC channel #gentoo-portage (webchat)
Bugs Related bugs
Lead(s)
Last elected: 2019-05-01
Member(s)
Subproject(s)
(and inherited member(s))
Parent Project Gentoo
Project listing

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 #gentoo-portage (webchat) IRC channel on the Libera.Chat 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 #Getting in touch 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 emerge --info 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

Note
Extensive history can be obtained by grafting the repository with the CVS conversion: git remote add history git+ssh://git@git.gentoo.org/archive/proj/portage-cvs.git && git fetch history && git replace --graft d9fc4acc572c6647a4f27b838d35d27d805d190e 1c683cd1ea7ad86047d39a068488c2eaa70751d3

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 please do not file issues here unless they pertain to the mirror. Pull requests are accepted and merged to the primary git repository.

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

  • master: the current main development line
  • 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 /checkouts/portage you'd set them like this:

CODE settings to use portage master branch
export PYTHONPATH="/checkouts/portage/lib${PYTHONPATH:+:}${PYTHONPATH}"
export PATH="/checkouts/portage/bin:${PATH}"

With those settings calling tools like emerge or ebuild 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. /checkouts/portage/bin/emerge instead of emerge).

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 to indent in bash files.
  • Use 4 spaces to indent in Python files.
  • 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 or add a new feature), add it to NEWS.

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 git send-email to gentoo-portage-dev@lists.gentoo.org.

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 gentoo-portage-dev@lists.gentoo.org 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 diff -u. 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 gentoo-portage-dev@lists.gentoo.org 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.

Major activities at the moment include:

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: gentoo-portage-dev@lists.gentoo.org.

In addition to the mailing list, we have an IRC channel on Libera.Chat: #gentoo-portage (webchat). 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, zmedico.

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.

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

Contributors with write access to portage.git

Name Nick
Brian Dolbec dolsen
Mike Gilbert floppym
Fabian Groffen grobian
James Le Cuirot chewi
John Helmert III ajak
Matt Turner mattst88
Michał Górny mgorny
Robin Johnson robbat2
Sam James sam
Sebastian Luther few
Ulrich Müller ulm
Zac Medico zmedico

See also

Resources offered by the Portage project on the wiki include:

Subpages

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

Devmanual project

External resources

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: carpaski, genone
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.

Retrieved from "https://wiki.gentoo.org/index.php?title=Project:Portage&oldid=1300174"