Project:Portage

From Gentoo Wiki
Revision as of 05:02, 25 January 2014 by Dol-sen (Talk | contribs)

Jump to: navigation, search
Portage
Description The Portage Development Project is devoted to maintaining and updating Portages core functionality and utilities.
Email gentoo-portage-dev@lists.gentoo.org
IRC Channel #gentoo-portage
Lead(s)
Members
Parent Project Gentoo Linux
Subprojects
Tags portage, emerge, portageq, repoman, ebuild
Project listing
Note
Please use the new gentoo github repo as a backup. It will become a mirror to git.overlays.gentoo.org.
    git remote add gentoo-hub git@github.com:gentoo/portage.git

Project Description

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 IRC channel on the freenode network.

Project Goals

The goal of the Portage Development Project stands at providing a seamless integration of developer and user tools to aid the growth and maintenance of the Gentoo Portage Tree.

Contributing to Portage

This project is undergoing some change. Zac Medico has stepped down as "Lead". That brings us to recruit additional members to help fill the productivity gap we have been experiencing. So all interested gentoo developers, please email the gentoo-portage-dev list stating your interest and any capabilities and desires you wish to bring to portage's development.

We will hold an election and project meeting for a new lead as soon as we get enough help to make it worthwhile.

While official project membership is restricted to official gentoo developers. I wish to acknowledge the many contributions from non-gentoo developers.

Contibuting Members

Member Nick Role
Arfrever Frehtes Taifersar Arahesis Arfrever member
Sebastian Luther few member
Alexander Berntsen bernalex member
Douglas Dunn djdunn new


Bug Reports

Please report all bugs you encounter on our bug tracking system . Before opening a new bug report please make sure that the bug has not already been reported by another user.


Important
Do not report bugs/requests about anything other than sys-apps/portage in the Portage Development product

In your bug report please state clearly:

  • 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

Please don't get too impatient if there is no immediate reaction to your bug, sometimes it can take a while before a developer has time to look at it (this also applies to non-Portage 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.

Testing multiple Portage versions

Note
This section only applies to Portage 2.1.2 or later

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.

As of Portage-2.1.2 one 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:

Codesettings to use portage master branch

export PYTHONPATH="/checkouts/portage/pym${PYTHONPATH:+:}${PYTHONPATH}"
export PATH="/checkouts/portage/bin:${PATH}"

With those settings calling tools like emerge , repoman or ebuild will pickup the correct locations to import libraries. External tools like gentoolkit or porthole may or may not respect those settings though. Setting PATH isn't even necessary if you always call the commands by their full name (e.g. /checkouts/portage/bin/emerge instead of emerge ).

Submitting Patches

If you want to submit a patch to sys-apps/portage or a related package, please make sure the patch follows these criteria:

  • Use TABS. Some people like 8 spaces, some people like 4, and some like 2. Tabs are the happy medium. Patches that use spaces and/or a mix of tabs and spaces for indentation will likely be rejected.
  • Generally submit diff files instead of whole files, only when the diff is significantly larger than the file itself or the file didn't exist previously submitting the whole file is acceptable.
  • Diffs have to be in unified form ( diff -u , git diff ).
  • Always submit a detailed explanation of what the patch does and, if necessary, why you chose the specific implementation you submitted (IOW: what's the benefit of the patch). Also include any problems and/or drawbacks you think the patch has.
  • Always state against which version (for releases) or revision and branch (for git patches) the patch was made.
  • Only submit clean patches. Do not include other patches in a submitted patch. If the code found in a patch does not match the description of the patch, it will be rejected. Also don't add any unrelated code cleanups in your patch
  • Python docstrings should conform to the Portage Docstring Specification.

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 mailing list and tag the subject with '[PATCH]'.

Note
Patches for packages NOT related to sys-apps/portage go on http://bugs.gentoo.org , please do not send them to the gentoo-portage-dev mailing list

Access to Portage GIT repositories

The Portage source code is maintained within a GIT repository on git.overlays.gentoo.org . If you are a dev: The main repository is located at git+ssh://git@git.overlays.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.

Note

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

  • master: the current main development line
  • prefix: experimental branch with support for prefix installs
  • public_api: a development branch to create a stable public interface to using portage directly in other applications.
Note
The old SVN repository is no longer available.

Resources

Resources offered by the Portage project are:

Sub-pages

External to wiki

External Documentation Resources

Unless otherwise noted the following resources are maintained by the documentation project , but as they are the primary online documentation for portage we will list them here.

Acknowledgements

We would like to thank the following authors and editors for their contributions to this guide:

  • carpaski
  • genone