path: root/glep-0049.rst

GLEP: 49
Title: Alternative Package Manager requirements
Version: $Revision$
Last-Modified: $Date$
Author: Paul de Vrieze <pauldv@gentoo.org>,
Status: Rejected
Type: Standards Track
Content-Type: text/x-rst
Created: 18-May-2006
Post-History: 19-May-2006, 6-Sep-2006

Note: This document needs to be relicensed to CC-BY-SA 3.0 after consulting
with the original author

Status
======

The council rejected this GLEP in favor of starting from a package manager
API and requiring Gentoo package managers in the tree to support that
API.  (That API is still pending, however.)


Abstract
========

This GLEP describes four classes of package managers. What the requirements for
them are, and what support they can receive.


Motivation
==========

To set a standard that package managers that seek Gentoo project approval and
support should adhere to.


Rationale
=========

Currently Portage is  showing its age. The  code of Portage does not  seem to be
salvageable for new versions. As of the date of publication, there are two known
alternative package managers that claim  a level of Portage compatibility. These
alternatives  are  `paludis`_ and  `pkgcore`_.   Before  these alternatives  are
developed further, a  set of rules should be created to  level the playing field
and ensuring that decisions can be made clearly.


Backwards Compatibility
=======================

Not a problem for this GLEP. There is no previous standard as the issue did not
exist before. This GLEP is to prevent future compatibility issues.


Categories of package managers
==============================

We distinguish four categories of package managers. While a package manager can
transition from one category to another, it can not be in two categories at the
same time. It can be in a state of transition though.

*Primary Package Manager*  
   There  is one primary  package manager.  Currently this  position is  held by
   Portage.  The primary  package manager  is assigned  by the  council  and all
   packages in the official tree must be installable by a usable version of the
   primary package manager.

*Candidate Primary Package Managers*
   A candidate  Primary Package Manager does  aim, or show an  aim, at replacing
   the current primary package manager. At  a point where the package manager is
   deemed stable  a decision  must be made  whether this package  manager should
   become the  new primary package manager.  At that point  the `Primary package
   manager transition phase`_ starts.

*Secondary Package Managers*
   A  secondary package  manager is  a package  manager that  coexists  with the
   primary package manager, while not aiming to replace it.  Examples of package
   managers that would fall into this category are:

   - Experimental package managers. Package managers  whose purpose it is to try
     out new features.

   - Focused package  managers. For example  a package manager that  allows the
     use of RPM formatted binary packages would be an example.

   - Alternate package managers.  Package managers that aim to  coexist with the
     primary  package  manager.  They  might  for example  offer  a  nicer  user
     interface  than the primary  package manager  (e.g. show  a cow  instead of
     compilation messages).


*Third Party Package Managers*
   A third party  package manager is any package  manager that lacks recognition
   from Gentoo as being in any other category. A third party package manager may
   or may not have a Gentoo package, but is not supported beyond that.


Package manager requirements
============================

As  a  package  manager is  in  a  state  of  higher  support there  are  higher
requirements to it. The purpose of  these requirements is to ensure the unity of
the distribution and the package tree.  For this purpose it is needed that there
is only one primary package manager. This is from Gentoo's perspective. From a
user perspective it is perfectly possible to use another package
manager. Candidate primary package managers and secondary package managers are
also supported in regards to bugs etc.


Primary package manager requirements
------------------------------------

The primary package  manager is the package manager that  sets the standards for
the  tree. All  ebuilds  in the  tree  must function  with  the primary  package
manager. As  the primary package manager sets  the standard it does  not have to
maintain compatibility with other package  managers. This does not mean that the
actual implementation is the standard, but that the maintainers have the ability
to define new standards, together with the other involved Gentoo projects.

The primary package manager does however have the responsibility that it must be
very stable.  The primary package  manager must maintain compatibility  with old
versions of itself  for extended periods of time. This  compatibility time is set
by the council. The  suggested time would be one year from  the point that there
is a compatible stable version for all supported architectures.

Another compatibility  requirement for the  primary package manager is  a limited
forward  compatibility.  It must  always  be  possible  to transition  from  the
unstable version of the primary package manager to a stable version. This may be
done either by first introducing reading compatibility for a new format and only
having write support  later. Another way would be the  provision of a conversion
tool that ensures that the on disk information maintained by the package manager
is supported by the stable package manager.

The primary package manager maintainers further have the responsibility to allow
competition. This means that reasonable patches from the maintainers of
secondary or candidate primary package managers must be applied, given that
these patches are as independent of that package manager as possible.

The primary package manager is maintained on official Gentoo infrastructure,
under control of Gentoo developers.


Candidate primary package manager requirements
------------------------------------------------

A  candidate  primary  package  manager  aims to  replace  the  primary  package
manager.  The council  is responsible  for deciding  whether this  is  done. The
requirements are  there to ensure that  it is actually possible  to transition a
candidate primary package manager into the primary package manager.

First of all,  there must exist a  transition path. This means that  the on disk
data of  the primary package manager  can be used  by (or converted to  a format
usable by) the candidate primary package manager.

Second, there  must be a test  path. It must  be possible for the  developers to
test out  the candidate primary package  manager on their  working systems. This
means that  the transition path  must exist. This  also means that there  are no
serious obstacles  for reverting  to the current  primary package  manager. This
reverting must  also be usable  when it is  decided that the candidate  will not
become primary package manager, for example because serious design flaws or bugs
were  found. Ideally,  the Candidate  Primary  Package Manager  and the  Primary
Package Manager can be installed simultaneously. If not, clear instructions must
be provided for both ways of transitioning.

Third, there  must exist an ebuild test  path.  It must be  possible for package
managers  to test  ebuilds in  one tree  for  both the  primary as  well as  the
candidate primary package manager. It is not an issue if this requires a special
mode for  the candidate primary  package manager. It  is not an issue  either if
compatibility can be  achieved by having the candidate primary package manager
unmerge the package.

Fourth, there must  be support. This means that the  package manager is actively
maintained  under  control  of  Gentoo.  If  it  is  not  maintained  on  Gentoo
infrastructure, the  means must be there  to move the package  manager, with its
change history, to Gentoo infrastructure.  This means that it must be maintained
on a  Gentoo supported versioning system,  or on a version  system whose history
can be converted to a Gentoo supported versioning system.

Fifth,  release capabilities.   There must  exist automated  tools that  use the
candidate  primary package  manager to  create release  media that  have similar
capabilities as those released using  the old primary package manager. The exact
requirements are determined  by the Release Engineering project,  but should not
be significantly beyond what is  currently implemented using the primary package
manager.


Secondary package manager requirements
--------------------------------------

A secondary package manager is a package manager that instead of directly aiming
at replacing the current primary package manager as primary package manager aims
to  cooperate with the  primary package  manager.  As  such a  secondary package
manager does not set  the standard on the tree, but follows  the standard set by
the primary package manager.

There are two  kinds of secondary package managers. The first  kind is formed by
those that do  not maintain their own installed package  database, but work with
the  package  database of  the  primary  package  manager. While  these  package
managers  can put  additional information  in the  database, these  entries must
remain compatible  with the  primary package managers.  Verification, reference,
and deinstallation by the primary package manager must remain functional.

The second  kind is  formed by  those package managers  that maintain  their own
package database,  or a package  database incompatible with the  primary package
manager. To ensure  the secondary role of these package  managers the support in
the tree for these package managers is provided along with restrictions.

The first restriction is that no packages in the tree must rely on the secondary
package  manager. While packages  may provide  a level  of support  (while being
compatible  with  the  primary  package  manager)  this  may  not  result  in  a
significant increase  of features.  If this  were allowed, this  would mean that
while they  technically work  with the primary  package manager, there  would be
significant incentive to  use the secondary package manager. As  the use of this
secondary  package manager  disallows the  parallel use  of the  primary package
manager, this would result in users using the secondary package manager as their
primary package manager.

Users are allowed to make their own  choices. However by making the tree favour a
package manager that  is not the primary package manager, this  will lead to the
secondary  package manager becoming  the effective  primary package  manager. As
this will be a decision by default  instead of a conscious choice by the council,
this is an undesirable result.

There is  one exclusion for the restriction  of packages that only  work with or
have  significant  improvements with  the  secondary  package  manager. That  is
packages  that by  their  nature are  only  usable with  this secondary  package
manager.   An example would  be a  graphical front-end  to the  secondary package
manager.

If a secondary  package manager works along the primary  package manager, but by
itself does not have the capabilities  of becoming a primary package manager the
risks of choice by  default are lower. As a result, the  council could choose to
allow the inclusion of packages that work only or significantly better with this
secondary  package manager.  For example  at a  point where  there is  a stable,
functional, package  manager that  can handle RPM  format packages,  the council
could decide  to include these packages  directly in the tree,  instead of using
wrapper  scripts  for  those  packages   that  are  only  provided  in  the  RPM
format. Such a  decision does imply that the maintainers  of the primary package
manager must take this secondary package manager into account.


Third party package manager requirements
----------------------------------------

A third party package manager is just  that. It is a package manager without any
support within Gentoo. As there is no control by Gentoo over the package manager
this means that there are no requirements on the package manager.

This complete  lack of control however  also translates to the  fact that Gentoo
can  not  make  package  manager   specific  changes  to  support  this  package
manager. Package manager  specific means that it is  possible to request changes
that  make the  tree  more independent  of  the primary  package manager.  These
changes must however be agnostic of the package manager, and only make it easier
to have alternative package managers.


Transition phases
=================

Primary package manager transition phase
----------------------------------------

A  candidate primary package  manager can  be chosen  to become  primary package
manager. This  can only happen by  council decision.  This decision  can only be
made  when  the  candidate primary  package  manager  is  stable on  all  stable
architectures.  (all  architectures  except   experimental  ones).  There  is  a
incubation  period of  at  least 3  months  before a  candidate primary  package
manager can become the primary package manager.

After the  decision has been  made to replace  the primary package  manager, the
transition phase starts.  The use of  the old stable package manager must remain
supported  for a  period of  6 months.  This means  that core  packages  must be
installable  by this  package manager.  Further the  possibility to  convert the
system automatically to the new primary package manager must be available for at
least  18 months,  but  preferably  longer (enable  installing  the new  package
manager from the old one).

During the  transition phase packages are allowed  in the tree that  use the new
features of the  new primary package manager. While  backward compatibility with
the previous primary package manager  must be maintained a forward compatibility
is no longer needed.


Secondary package manager to candidate primary package manager transition
-------------------------------------------------------------------------

The  transition from  secondary  package manager  to  candidate primary  package
manager  is straightforward.  The  secondary package  manager  must satisfy  all
requirements  for  a  candidate  primary  package manager.  At  that  point  its
maintainers can announce that they  are changing the status to candidate primary
package manager.  This allows  a greater support  from Gentoo in  achieving that
goal.


Third party to other transition
-------------------------------

When a third party package manager wants to transition into one of the other
categories (except primary package manager) it must satisfy all requirements for
that category.


References
==========

.. _paludis: http://paludis.berlios.de/
.. _pkgcore: http://gentooexperimental.org/~ferringb/bzr/pkgcore/
.. _Open Publication License: http://www.opencontent.org/openpub/


Copyright
=========

This document is copyright 2006 by Paul de Vrieze and licensed under the
`Open Publication License`_.