en/glep/glep-0049.txt

GLEP: 49
Title: Alternative Package Manager requirements
Version: $Revision: 1.3 $
Last-Modified: $Date: 2006/05/21 10:23:55 $
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

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`_.
1	pauldv	1.1	GLEP: 49
2			Title: Alternative Package Manager requirements
3	g2boojum	1.4	Version: $Revision: 1.3 $
4			Last-Modified: $Date: 2006/05/21 10:23:55 $
5	pauldv	1.1	Author: Paul de Vrieze <pauldv@gentoo.org>,
6	g2boojum	1.4	Status: Rejected
7	pauldv	1.1	Type: Standards Track
8			Content-Type: text/x-rst
9			Created: 18-May-2006
10	g2boojum	1.4	Post-History: 19-May-2006, 6-Sep-2006
11
12			Status
13			======
14
15			The council rejected this GLEP in favor of starting from a package manager
16			API and requiring Gentoo package managers in the tree to support that
17			API. (That API is still pending, however.)
18	pauldv	1.1
19
20			Abstract
21			========
22
23			This GLEP describes four classes of package managers. What the requirements for
24			them are, and what support they can receive.
25
26
27			Motivation
28			==========
29
30	pauldv	1.2	To set a standard that package managers that seek Gentoo project approval and
31	pauldv	1.1	support should adhere to.
32
33
34			Rationale
35			=========
36
37	pauldv	1.2	Currently Portage is showing its age. The code of Portage does not seem to be
38			salvageable for new versions. As of the date of publication, there are two known
39			alternative package managers that claim a level of Portage compatibility. These
40			alternatives are `paludis`_ and `pkgcore`_. Before these alternatives are
41			developed further, a set of rules should be created to level the playing field
42			and ensuring that decisions can be made clearly.
43	pauldv	1.1
44
45			Backwards Compatibility
46			=======================
47
48			Not a problem for this GLEP. There is no previous standard as the issue did not
49			exist before. This GLEP is to prevent future compatibility issues.
50
51
52			Categories of package managers
53			==============================
54
55			We distinguish four categories of package managers. While a package manager can
56			transition from one category to another, it can not be in two categories at the
57			same time. It can be in a state of transition though.
58
59			Primary Package Manager
60			There is one primary package manager. Currently this position is held by
61	pauldv	1.2	Portage. The primary package manager is assigned by the council and all
62			packages in the official tree must be installable by a usable version of the
63	pauldv	1.1	primary package manager.
64
65			Candidate Primary Package Managers
66			A candidate Primary Package Manager does aim, or show an aim, at replacing
67			the current primary package manager. At a point where the package manager is
68			deemed stable a decision must be made whether this package manager should
69	pauldv	1.2	become the new primary package manager. At that point the `Primary package
70	pauldv	1.1	manager transition phase`_ starts.
71
72			Secondary Package Managers
73			A secondary package manager is a package manager that coexists with the
74	pauldv	1.2	primary package manager, while not aiming to replace it. Examples of package
75			managers that would fall into this category are:
76	pauldv	1.1
77			- Experimental package managers. Package managers whose purpose it is to try
78			out new features.
79
80	pauldv	1.2	- Focused package managers. For example a package manager that allows the
81			use of RPM formatted binary packages would be an example.
82
83			- Alternate package managers. Package managers that aim to coexist with the
84			primary package manager. They might for example offer a nicer user
85			interface than the primary package manager (e.g. show a cow instead of
86			compilation messages).
87	pauldv	1.1
88
89			Third Party Package Managers
90			A third party package manager is any package manager that lacks recognition
91	pauldv	1.2	from Gentoo as being in any other category. A third party package manager may
92			or may not have a Gentoo package, but is not supported beyond that.
93	pauldv	1.1
94
95			Package manager requirements
96			============================
97
98			As a package manager is in a state of higher support there are higher
99			requirements to it. The purpose of these requirements is to ensure the unity of
100			the distribution and the package tree. For this purpose it is needed that there
101	pauldv	1.3	is only one primary package manager. This is from gentoo's perspective. From a
102			user perspective it is perfectly possible to use another package
103			manager. Candidate primary package managers and secondary package managers are
104			also supported in regards to bugs etc.
105	pauldv	1.1
106
107	pauldv	1.2	Primary package manager requirements
108	pauldv	1.1	------------------------------------
109
110			The primary package manager is the package manager that sets the standards for
111			the tree. All ebuilds in the tree must function with the primary package
112			manager. As the primary package manager sets the standard it does not have to
113	pauldv	1.3	maintain compatibility with other package managers. This does not mean that the
114			actual implementation is the standard, but that the maintainers have the ability
115			to define new standards, together with the other involved gentoo projects.
116	pauldv	1.1
117			The primary package manager does however have the responsibility that it must be
118			very stable. The primary package manager must maintain compatibility with old
119	pauldv	1.2	versions of itself for extended periods of time. This compatibility time is set
120	pauldv	1.1	by the council. The suggested time would be one year from the point that there
121			is a compatible stable version for all supported architectures.
122
123	pauldv	1.2	Another compatibility requirement for the primary package manager is a limited
124	pauldv	1.1	forward compatibility. It must always be possible to transition from the
125			unstable version of the primary package manager to a stable version. This may be
126			done either by first introducing reading compatibility for a new format and only
127			having write support later. Another way would be the provision of a conversion
128			tool that ensures that the on disk information maintained by the package manager
129			is supported by the stable package manager.
130
131	pauldv	1.3	The primary package manager maintainers further have the responsibility to allow
132			competition. This means that reasonable patches from the maintainers of
133			secondary or candidate primary package managers must be applied, given that
134			these patches are as independent of that package manager as possible.
135
136	pauldv	1.2	The primary package manager is maintained on official Gentoo infrastructure,
137			under control of Gentoo developers.
138	pauldv	1.1
139
140	pauldv	1.2	Candidate primary package manager requirements
141	pauldv	1.1	------------------------------------------------
142
143			A candidate primary package manager aims to replace the primary package
144			manager. The council is responsible for deciding whether this is done. The
145			requirements are there to ensure that it is actually possible to transition a
146			candidate primary package manager into the primary package manager.
147
148			First of all, there must exist a transition path. This means that the on disk
149			data of the primary package manager can be used by (or converted to a format
150			usable by) the candidate primary package manager.
151
152			Second, there must be a test path. It must be possible for the developers to
153			test out the candidate primary package manager on their working systems. This
154			means that the transition path must exist. This also means that there are no
155	pauldv	1.2	serious obstacles for reverting to the current primary package manager. This
156			reverting must also be usable when it is decided that the candidate will not
157			become primary package manager, for example because serious design flaws or bugs
158			were found. Ideally, the Candidate Primary Package Manager and the Primary
159			Package Manager can be installed simultaneously. If not, clear instructions must
160			be provided for both ways of transitioning.
161	pauldv	1.1
162			Third, there must exist an ebuild test path. It must be possible for package
163			managers to test ebuilds in one tree for both the primary as well as the
164			candidate primary package manager. It is not an issue if this requires a special
165			mode for the candidate primary package manager. It is not an issue either if
166	pauldv	1.2	compatibility can be achieved by having the candidate primary package manager
167			unmerge the package.
168	pauldv	1.1
169			Fourth, there must be support. This means that the package manager is actively
170	pauldv	1.2	maintained under control of Gentoo. If it is not maintained on Gentoo
171	pauldv	1.1	infrastructure, the means must be there to move the package manager, with its
172	pauldv	1.2	change history, to Gentoo infrastructure. This means that it must be maintained
173			on a Gentoo supported versioning system, or on a version system whose history
174			can be converted to a Gentoo supported versioning system.
175
176			Fifth, release capabilities. There must exist automated tools that use the
177			candidate primary package manager to create release media that have similar
178			capabilities as those released using the old primary package manager. The exact
179			requirements are determined by the Release Engineering project, but should not
180			be significantly beyond what is currently implemented using the primary package
181			manager.
182	pauldv	1.1
183
184	pauldv	1.2	Secondary package manager requirements
185	pauldv	1.1	--------------------------------------
186
187			A secondary package manager is a package manager that instead of directly aiming
188	pauldv	1.2	at replacing the current primary package manager as primary package manager aims
189			to cooperate with the primary package manager. As such a secondary package
190	pauldv	1.1	manager does not set the standard on the tree, but follows the standard set by
191			the primary package manager.
192
193			There are two kinds of secondary package managers. The first kind is formed by
194			those that do not maintain their own installed package database, but work with
195			the package database of the primary package manager. While these package
196			managers can put additional information in the database, these entries must
197			remain compatible with the primary package managers. Verification, reference,
198			and deinstallation by the primary package manager must remain functional.
199
200			The second kind is formed by those package managers that maintain their own
201			package database, or a package database incompatible with the primary package
202			manager. To ensure the secondary role of these package managers the support in
203	pauldv	1.3	the tree for these package managers is provided along with restrictions.
204	pauldv	1.1
205			The first restriction is that no packages in the tree must rely on the secondary
206			package manager. While packages may provide a level of support (while being
207			compatible with the primary package manager) this may not result in a
208	pauldv	1.2	significant increase of features. If this were allowed, this would mean that
209	pauldv	1.1	while they technically work with the primary package manager, there would be
210			significant incentive to use the secondary package manager. As the use of this
211	pauldv	1.2	secondary package manager disallows the parallel use of the primary package
212	pauldv	1.1	manager, this would result in users using the secondary package manager as their
213			primary package manager.
214
215	pauldv	1.2	Users are allowed to make their own choices. However by making the tree favour a
216	pauldv	1.1	package manager that is not the primary package manager, this will lead to the
217	pauldv	1.2	secondary package manager becoming the effective primary package manager. As
218			this will be a decision by default instead of a conscious choice by the council,
219	pauldv	1.1	this is an undesirable result.
220
221			There is one exclusion for the restriction of packages that only work with or
222			have significant improvements with the secondary package manager. That is
223			packages that by their nature are only usable with this secondary package
224	pauldv	1.2	manager. An example would be a graphical front-end to the secondary package
225	pauldv	1.1	manager.
226
227			If a secondary package manager works along the primary package manager, but by
228			itself does not have the capabilities of becoming a primary package manager the
229			risks of choice by default are lower. As a result, the council could choose to
230			allow the inclusion of packages that work only or significantly better with this
231			secondary package manager. For example at a point where there is a stable,
232			functional, package manager that can handle RPM format packages, the council
233			could decide to include these packages directly in the tree, instead of using
234			wrapper scripts for those packages that are only provided in the RPM
235			format. Such a decision does imply that the maintainers of the primary package
236			manager must take this secondary package manager into account.
237
238
239	pauldv	1.2	Third party package manager requirements
240	pauldv	1.1	----------------------------------------
241
242			A third party package manager is just that. It is a package manager without any
243	pauldv	1.2	support within Gentoo. As there is no control by Gentoo over the package manager
244	pauldv	1.1	this means that there are no requirements on the package manager.
245
246	pauldv	1.2	This complete lack of control however also translates to the fact that Gentoo
247	pauldv	1.1	can not make package manager specific changes to support this package
248			manager. Package manager specific means that it is possible to request changes
249			that make the tree more independent of the primary package manager. These
250			changes must however be agnostic of the package manager, and only make it easier
251			to have alternative package managers.
252
253
254	pauldv	1.2	Transition phases
255	pauldv	1.1	=================
256
257	pauldv	1.2	Primary package manager transition phase
258	pauldv	1.1	----------------------------------------
259
260			A candidate primary package manager can be chosen to become primary package
261	pauldv	1.3	manager. This can only happen by council decision. This decision can only be
262			made when the candidate primary package manager is stable on all stable
263			architectures. (all architectures except experimental ones). There is a
264			incubation period of at least 3 months before a candidate primary package
265			manager can become the primary package manager.
266	pauldv	1.1
267			After the decision has been made to replace the primary package manager, the
268			transition phase starts. The use of the old stable package manager must remain
269			supported for a period of 6 months. This means that core packages must be
270			installable by this package manager. Further the possibility to convert the
271			system automatically to the new primary package manager must be available for at
272			least 18 months, but preferably longer (enable installing the new package
273			manager from the old one).
274
275			During the transition phase packages are allowed in the tree that use the new
276			features of the new primary package manager. While backward compatibility with
277			the previous primary package manager must be maintained a forward compatibility
278			is no longer needed.
279
280
281			Secondary package manager to candidate primary package manager transition
282			-------------------------------------------------------------------------
283
284			The transition from secondary package manager to candidate primary package
285			manager is straightforward. The secondary package manager must satisfy all
286			requirements for a candidate primary package manager. At that point its
287			maintainers can announce that they are changing the status to candidate primary
288	pauldv	1.2	package manager. This allows a greater support from Gentoo in achieving that
289	pauldv	1.1	goal.
290
291
292			Third party to other transition
293			-------------------------------
294
295			When a third party package manager wants to transition into one of the other
296			categories (except primary package manager) it must satisfy all requirements for
297			that category.
298
299
300			References
301			==========
302
303			.. _paludis: http://paludis.berlios.de/
304			.. _pkgcore: http://gentooexperimental.org/~ferringb/bzr/pkgcore/
305			.. _Open Publication License: http://www.opencontent.org/openpub/
306
307
308			Copyright
309			=========
310
311			This document is copyright 2006 by Paul de Vrieze and licensed under the
312			`Open Publication License`_.