en/glep/glep-0054.txt

GLEP: 54
Title: scm package version suffix
Version: $Revision: 1.4 $
Last-Modified: $Date: 2007/12/17 18:42:33 $
Author: Piotr Jaroszyński <peper@gentoo.org>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 09-Dec-2007
Post-History: 09-Dec-2007

Abstract
========

This GLEP proposes addition of a new special package version suffix - ``scm`` -
for ebuilds checking out source directly from a source code management system.

Motivation
==========

Currently there is no standard way of identifying SCM ebuilds. Using 9999 as the
version is pretty common, but it is handled like any other ebuild and hence
portage cannot provide any additional features for packages with such a version.
Another way is adding a separate package with a -cvs suffix in its name, but 
that forces the author to use ``|| ( cat/pkg cat/pkg-cvs )`` dependencies. The
closest to what is proposed in this GLEP is the ``cvs`` version part, but its
implementation is of very limited use. It has strange comparison rules, no
documentation, has been used sparingly (if ever) and has a misleading name.

The possibility for package managers to recognise SCM ebuilds would allow them
to add features dedicated specially to said ebuilds. One such feature could be
automatic re-installation of SCM packages once a day or week.  Any
specifications for such features are beyond the scope of this GLEP.

Specification
=============


``scm`` is a special suffix. It can be used on its own, but also in any other
valid version spec, just before the place where revision would go. And just like
revision it can be used only once in a version spec, e.g.:

  *  ``cat/pkg-1.0_alpha0-scm``
  *  ``cat/pkg-1.0_alpha-scm``
  *  ``cat/pkg-1.0-scm-r3``
  *  ``cat/pkg-1-scm``
  *  ``cat/pkg-1-scm-r2``
  *  ``cat/pkg-scm``

These package atoms are sorted in ascending order (see `Version Comparison`_).

Version Comparison
==================

The addition of the scm suffix yields changes in version comparison:

  *  When comparing version components from left to right the scm component has the
     highest priority over other version components.  Hence 
     ``pkg-1_alpha-r3 < pkg-1-scm``, 'scm' is greater than 'alpha-r3'.
  *  Current suffixes with no number part no longer default to zero if they are
     followed by an scm suffix. If that's the case the number part is considered
     to be of a maximum value. Hence ``1_alpha2-scm < 1_alpha-scm``, but still
     ``1_alpha == 1_alpha0``.  The rationale behind this choice is to allow
     multiple branches.  For instance imagine a package with an alpha branch
     and multiple scm releases, as the following: ``alpha-scm``,
     ``alpha2-scm``, ``alpha3-scm`` and so forth.  The desired outcome is
     for ``alpha-scm`` to be greater than all other branches of the same tree.

Example parsing:

  *  ``cat/pkg-scm > cat/pkg-1``
       When parsing from left to right the first difference is ``scm`` and
       ``1``. ``cat/pkg-scm`` wins.
  *  ``cat/pkg-1-scm > cat/pkg-1.0-scm``
       When parsing from left to right the first difference is ``scm`` and
       ``0``. ``cat/pkg-1-scm`` wins.
  *  ``cat/pkg-1_alpha-scm > cat/pkg-1_alpha1-scm``
       In the first package version ``alpha`` doesn't have a number part *and*
       is followed by an ``scm`` suffix, hence it is considered to have a maximum
       value as the number part. When parsing from left to right the first
       difference is the number part of the ``alpha`` suffix. Maximum value
       yielded by the following ``scm`` suffix wins with ``1``.

List of version specs in ascending order:

  *  ``1``
  *  ``1.1-scm``
  *  ``1.2_alpha-scm``
  *  ``1.2_beta_p``
  *  ``1.2_beta_p0-scm``
  *  ``1.2_beta_p1-scm``
  *  ``1.2_beta_p-scm``
  *  ``1.2_beta1_p-scm``
  *  ``1.2_beta10``
  *  ``1.2_beta10_p1-scm``
  *  ``1.2_beta10-scm``
  *  ``1.2_beta-scm``
  *  ``1.2``
  *  ``1.2-scm``
  *  ``1.2-scm-r1``
  *  ``1-scm``
  *  ``10``
  *  ``scm``
  *  ``scm-r3``


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

Portage versions prior to 2.1.2.12 (included in 2007.0) don't handle arbitrary
version suffixes and die during various tasks making portage hard or impossible
to use. Later versions just ignore them displaying warnings. Hence use of
``scm`` suffixes in gentoo-x86 tree will probably have to wait till 2008.0
release or later.

Copyright
=========

This document has been placed in the public domain.

.. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et :
1	antarus	1.1	GLEP: 54
2	peper	1.4	Title: scm package version suffix
3	antarus	1.5	Version: $Revision: 1.4 $
4			Last-Modified: $Date: 2007/12/17 18:42:33 $
5	peper	1.4	Author: Piotr Jaroszyński <peper@gentoo.org>
6			Status: Draft
7			Type: Standards Track
8	antarus	1.1	Content-Type: text/x-rst
9	peper	1.4	Created: 09-Dec-2007
10			Post-History: 09-Dec-2007
11	antarus	1.1
12			Abstract
13			========
14
15	peper	1.4	This GLEP proposes addition of a new special package version suffix - ``scm`` -
16			for ebuilds checking out source directly from a source code management system.
17	antarus	1.1
18			Motivation
19			==========
20
21	antarus	1.5	Currently there is no standard way of identifying SCM ebuilds. Using 9999 as the
22	peper	1.4	version is pretty common, but it is handled like any other ebuild and hence
23			portage cannot provide any additional features for packages with such a version.
24	antarus	1.5	Another way is adding a separate package with a -cvs suffix in its name, but
25			that forces the author to use ``\|\| ( cat/pkg cat/pkg-cvs )`` dependencies. The
26			closest to what is proposed in this GLEP is the ``cvs`` version part, but its
27			implementation is of very limited use. It has strange comparison rules, no
28			documentation, has been used sparingly (if ever) and has a misleading name.
29	peper	1.4
30			The possibility for package managers to recognise SCM ebuilds would allow them
31			to add features dedicated specially to said ebuilds. One such feature could be
32	antarus	1.5	automatic re-installation of SCM packages once a day or week. Any
33			specifications for such features are beyond the scope of this GLEP.
34	antarus	1.1
35	peper	1.4	Specification
36			=============
37	antarus	1.1
38	antarus	1.5
39	peper	1.4	``scm`` is a special suffix. It can be used on its own, but also in any other
40			valid version spec, just before the place where revision would go. And just like
41			revision it can be used only once in a version spec, e.g.:
42
43			* ``cat/pkg-1.0_alpha0-scm``
44			* ``cat/pkg-1.0_alpha-scm``
45			* ``cat/pkg-1.0-scm-r3``
46			* ``cat/pkg-1-scm``
47			* ``cat/pkg-1-scm-r2``
48			* ``cat/pkg-scm``
49
50			These package atoms are sorted in ascending order (see `Version Comparison`_).
51
52			Version Comparison
53			==================
54
55			The addition of the scm suffix yields changes in version comparison:
56
57			* When comparing version components from left to right the scm component has the
58	antarus	1.5	highest priority over other version components. Hence
59			``pkg-1_alpha-r3 < pkg-1-scm``, 'scm' is greater than 'alpha-r3'.
60	peper	1.4	* Current suffixes with no number part no longer default to zero if they are
61			followed by an scm suffix. If that's the case the number part is considered
62			to be of a maximum value. Hence ``1_alpha2-scm < 1_alpha-scm``, but still
63	antarus	1.5	``1_alpha == 1_alpha0``. The rationale behind this choice is to allow
64			multiple branches. For instance imagine a package with an alpha branch
65			and multiple scm releases, as the following: ``alpha-scm``,
66			``alpha2-scm``, ``alpha3-scm`` and so forth. The desired outcome is
67			for ``alpha-scm`` to be greater than all other branches of the same tree.
68	peper	1.4
69			Example parsing:
70
71			* ``cat/pkg-scm > cat/pkg-1``
72			When parsing from left to right the first difference is ``scm`` and
73			``1``. ``cat/pkg-scm`` wins.
74			* ``cat/pkg-1-scm > cat/pkg-1.0-scm``
75			When parsing from left to right the first difference is ``scm`` and
76			``0``. ``cat/pkg-1-scm`` wins.
77			* ``cat/pkg-1_alpha-scm > cat/pkg-1_alpha1-scm``
78			In the first package version ``alpha`` doesn't have a number part and
79			is followed by an ``scm`` suffix, hence it is considered to have a maximum
80			value as the number part. When parsing from left to right the first
81			difference is the number part of the ``alpha`` suffix. Maximum value
82			yielded by the following ``scm`` suffix wins with ``1``.
83
84			List of version specs in ascending order:
85
86			* ``1``
87			* ``1.1-scm``
88			* ``1.2_alpha-scm``
89			* ``1.2_beta_p``
90			* ``1.2_beta_p0-scm``
91			* ``1.2_beta_p1-scm``
92			* ``1.2_beta_p-scm``
93			* ``1.2_beta1_p-scm``
94			* ``1.2_beta10``
95			* ``1.2_beta10_p1-scm``
96			* ``1.2_beta10-scm``
97			* ``1.2_beta-scm``
98			* ``1.2``
99			* ``1.2-scm``
100			* ``1.2-scm-r1``
101			* ``1-scm``
102			* ``10``
103			* ``scm``
104			* ``scm-r3``
105	antarus	1.1
106
107			Backwards Compatibility
108			=======================
109
110	peper	1.4	Portage versions prior to 2.1.2.12 (included in 2007.0) don't handle arbitrary
111			version suffixes and die during various tasks making portage hard or impossible
112			to use. Later versions just ignore them displaying warnings. Hence use of
113			``scm`` suffixes in gentoo-x86 tree will probably have to wait till 2008.0
114			release or later.
115	antarus	1.1
116			Copyright
117			=========
118
119			This document has been placed in the public domain.
120
121	peper	1.4	.. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et :