[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Warren's Package Naming Proposal - Revision 2



http://www.fedora.us/wiki/PackageNamingGuidelines
The following is based upon current fedora.us package naming guidelines, 
edited and dramatically simplified because fedora.redhat.com no longer 
needs many of fedora.us special considerations.

http://www.redhat.com/archives/fedora-devel-list/2003-October/msg01152.html
This is Revision 1 from October 31st, 2003

The below proposal is ALMOST EXACTLY THE SAME as fedora.us current 
scheme except with the leading "0.fdr." removed from all %{release} tags 
and %{reptag} added to the end.  I would assert that fedora.us package 
naming scheme has demonstrated to be a great success, thus it should 
continued in fedora.redhat.com.  The below scheme is also in-line with 
the common practices used by most of Red Hat's existing packages.

Dispersed within the below draft are "XXX" sections where discussions 
are still necessary.  The revision history of section iii otherwise 
notes sections that have been changed since Revision 1.  Section C-7 at 
the bottom is the most important part in this revision.



**Fedora Package Naming Guidelines
Warren's Proposal for fedora.redhat.com
Revision 2
================================
i. Introduction
   Goals for package naming guidelines
ii. Terminology
iii. Revision History
A. Package Name
B. Version
C. Release Tag
    1. Release Prefix
    2. Vepoch
    3. Non-Numeric Version to Release
    4. Dist tag
    5. Special: Kernel modules
    6. Special: Plugin, theme etc packages
    7. Special: Repository Tag

i. Introduction
===============
Goals for the Fedora Package Naming Guidelines
* Easily understandable package naming policy
* Indication of the original source version (end-user convenience)
* Allow for a smooth upgrade path between multiple levels of testing
branches and future distribution upgrades.  This means E-V-R must never
be exactly identical between distribution versions.
* Minimize the chance of package conflicts for future Fedora
distribution upgrades.

ii. Terminology
==============
name
This is the "Name" field of RPM .spec files.

version
This is the "Version" field of RPM .spec files.

release tag
This is the "Release" field of RPM .spec files.

dist tag
This is a distribution tag indicating which RHL/FC distribution this
package is intended for.  This only occurs in cases where packages from
different distributions are built from the same SRPM and patchlevel.

vepoch
This is our term for "version specific epoch", used in all packages as a 
simple means of ensuring upgrades by simple incrementing the leading 
number within the release tag.  vepoch is otherwise known as "release 
number" or "patchlevel".  Read C-2 for more information.

XXX: For now I am keeping the term vepoch in this draft because a better 
alternative has not been proposed.  I personally feel that "release 
number" most effectively communicates what this number is about, however 
"release number" is confusingly similar to "release tag" no?  "release 
tag" == %{release}
Please discuss this... we need only choose a name to replace vepoch.
XXX

E-V-R
Abbreviation for epoch, version, and release.  This is often referred to
when talking about potential package upgrading problems.


iii. Revision History
=====================
07 October 2003 Draft Revision 2
  * C-7 minor number is now %{reptag} for marking repositories and 3rd 
party repositories.
  * Many XXX sections needing discussion before changes in Draft Revision 3.
31 October 2003 Draft Revision 1.
  * Initial post for fedora.redhat.com.



A. Package Name
===============
Package name should preferably match the upstream tarball or project
name from which this software came.  In some cases this naming choice is
more complicated.  If this package has been packaged by other
distributions/packagers (Mandrake, SuSE, Conectiva, PLD, PLF, FreshRPMS,
etc.) in the past, then we should try to match their name for
consistency.  In any case, try to use your best judgment, and other
developers will help in the final decision.

Ultimately it is up to QA to decide upon the proper %{name} before 
publication.

B. Version
==========
If the version is only numbers, then these numbers can be put into the
"version" field of the RPM .spec unchanged.  If the version contains
non-numeric characters, this creates several problems for RPM version
comparison and a broken upgrade path.

Example:
foobar-1.2.3beta1.tar.gz
foobar-1.2.3.tar.gz

While the "1.2.3" version is newer than the 1.2.3beta1 version, RPM
version comparison thinks the former is newer.

Example:
foobar-1.0a
foobar-1.0b

The "1.0b" version is higher than "1.0a", but all versions of RPM prior
to rpm-4.2-0.55 are confused when it tries to compare letters. Whichever
package is first in the comparison "wins", thus this becomes a  two way
upgrade problem.  This a < b comparison works properly only in RH9 and 
higher.

For simplicity, Fedora treats both pre-release and post-release
non-numeric version cases the same, making the version purely numeric
and moving the alphabetic part to the release tag.  Take the numeric
portion of the source version and make that the package version tag.

Read C-3 for more details.

XXX:
Read section C-3 for the very important discussion necessary for 
removing the post-release requirement in non-numeric %{version} tags.
XXXX

C. Release Tag
==============
The release tag of Fedora packages more complicated, so this is split
into several parts.

C-1. Release Prefix
-------------------
No longer needed in fedora.redhat.com.

C-2. Vepoch
-----------
The leftmost leading number within the release tag is the "version 
specific epoch" or vepoch in Fedora.  This number is incremented with 
every package update.  The vepoch is otherwise known as the "release 
number" or "patchlevel".

The key difference between the concept of "vepoch" and "patch level" is 
that everything to the right of the vepoch is PURELY INFORMATIONAL.  The 
only time where it matters is to guarantee a different %{release} tag 
between two distribution versions.

The vepoch is to be respected by Fedora Core/Extras/Alternatives/Legacy 
as canonical.  Package updates in any repository should always check all 
other official repositories to be sure that the vepoch is always 
incremented and never matching an existing package.

With most normal packages, vepoch is a single number starting at "1".
Under the (C-3) non-numeric version case it is two numbers starting at
"0.1" with the second number being the number to increment.

Normal Package Example:
     foobar-1.2.3-1.src.rpm compiles to
     foobar-1.2.3-1.i386.rpm

If this package is patched:
     foobar-1.2.3-2.i386.rpm
     foobar-1.2.3-3.i386.rpm

XXX:
Read section ii. near the top regarding the discussion necessary in 
renaming of vepoch within the naming guidelines.
XXX


C-3. Non-Numeric Version to Release
-----------------------------------
As mentioned above in section B (Version) and C-2 (Vepoch), non-numeric 
versioned packages can be problematic so they must be treated with care. 
 These are cases where the upstream version has letters rather than 
simple numbers in their version.  Often they have tags like alpha, beta, 
rc, or letters like a and b denoting that it is a version before or 
after the number.  Read section B to understand why we cannot simply put 
these letters into the version tag.

Release Tag for Pre-Release Packages:
     0.%{X}.%{alphatag}
Release Tag for Non-Numeric Post-Release Packages:
     %{X}.%{alphatag}
Where %{X} is the vepoch increment, and %{alphatag} is the string that
came from the version.

Example (pre-release):
     mozilla-1.4a.tar.gz   from upstream is lower than
     mozilla-1.4.tar.gz    the later "final" version thus
     mozilla-1.4-0.1.a     Fedora package name

Example (pre-release):
     alsa-lib-0.9.2beta1.tar.gz  becomes
     alsa-lib-0.9.2-0.1.beta1

Example (post-release):
     gkrellm-2.1.7.tar.gz
     gkrellm-2.1.7a.tar.gz       Quick bugfix release after 2.1.7
     gkrellm-2.1.7-1.a

Upgrade Path Example (mozilla):
     mozilla-1.4-0.1.a
         Patched
     mozilla-1.4-0.2.a
         Patched again
     mozilla-1.4-0.3.a
         Move to 1.4b
     mozilla-1.4-0.4.b
         Patched
     mozilla-1.4-0.5.b
         Move to 1.4 "final" version
         Notice that this becomes a normal C-2 case
     mozilla-1.4-1
         Patched
     mozilla-1.4-2

Upgrade Path Example (alsa-lib):
     alsa-lib-0.9.2-0.1.beta1
         Patched
     alsa-lib-0.9.2-0.2.beta1
         Move to beta2
     alsa-lib-0.9.2-0.3.beta2
         Move to beta3 and simultaneously patch
     alsa-lib-0.9.2-0.4.beta3
         Patched again
     alsa-lib-0.9.2-0.5.beta3
         Move to rc1
     alsa-lib-0.9.2-0.6.rc1
         Move to rc2
     alsa-lib-0.9.2-0.7.rc2
         Move to "final"
     alsa-lib-0.9.2-1
         Patched
     alsa-lib-0.9.2-2

XXX: Please discuss this:
We should change the post-release case to no longer be effected by the 
non-numeric %{version} rule since rpm-4.2 in RH9 and higher are not 
effected by this problem.  Furthermore (and by accident) rpm python 
bindings since rpm-4.1 of RH8 have behaved in a proper fashion while rpm 
itself did not, and apt-get has always behaved "properly" when comparing 
numbers to letters, or letters to letters.  In any case Fedora Legacy 
has already agreed that upgrading rpm to the latest version must be done 
as the first requirement for all users who will be using Fedora Legacy.

For these reasons we probably *can* allow non-numeric characters into 
the version only in certain cases where it is ABSOLUTELY CERTAIN it will 
not lead to an epoch increment in the future.

Mike Harris brought up the example of the "imap" package with its 
strange versioning.  In some cases like that, we may need to grandfather 
some packages in.
This point needs a LOT more analysis before being ratified, so please 
discuss this.  Do not contribute to this part of the thread unless you 
truly know what you are talking about.  No speculation please.
XXX


C-4. Dist tag
-------------
In cases where the same SRPM and patchlevel is used between two or more 
distributions supported by Fedora, a dist tag is appended to the end of 
the release tag defined in C-2 and C-3.  The dist tags with the 
following examples appear to be only cosmetic, however the a different 
E-V-R is needed between distributions to ensure dist upgrading works 
fully in all corner cases.

Dist Tag for Normal Packages:
     %{X}.%{disttag}
Where %{X} is the vepoch and %{disttag} is a distribution tag from this 
table:

0.7.3 Red Hat Linux 7.3
0.8   Red Hat Linux 8
0.9   Red Hat Linux 9
1     Fedora Core 1
1.93  Fedora Core 1.93 beta
1.94  Fedora Core 1.94 beta
2     Fedora Core 2 beta

Example:
     foobar-1.2.3-1.0.7.3.i386.rpm
     foobar-1.2.3-1.0.8.i386.rpm
     foobar-1.2.3-1.0.9.i386.rpm
     foobar-1.2.3-1.1.94.i386.rpm
     foobar-1.2.3-1.2.i386.rpm

Upgrade Path Example (FC1 only shown):
     foobar-1.2.3-1.1.i386.rpm
     foobar-1.2.3-2.1.i386.rpm
     foobar-1.2.3-3.1.i386.rpm


Dist Tag for Pre-Release Packages:
     %{X}.%{alphatag}.%{disttag}
Where %{X} is the vepoch, %{alphatag} is the pre-release tag described 
in C-3, %{disttag} is a distribution tag described above.

Example:
     alsa-lib-0.9.2-0.1.beta1.0.8.i386.rpm
alsa-lib for RH 8.0
     alsa-lib-0.9.2-0.1.beta1.1.i386.rpm
alsa-lib for FC1

Upgrade Path Example (RH 7.3 only shown):
     alsa-lib-0.9.2-0.1.beta1.0.7.3
     alsa-lib-0.9.2-0.2.beta1.0.7.3
     alsa-lib-0.9.2-0.3.beta2.0.7.3
     alsa-lib-0.9.2-0.4.beta3.0.7.3
     alsa-lib-0.9.2-0.5.beta3.0.7.3
     alsa-lib-0.9.2-0.6.rc1.0.7.3
     alsa-lib-0.9.2-0.7.rc2.0.7.3
     alsa-lib-0.9.2-1.0.7.3
     alsa-lib-0.9.2-2.0.7.3

XXX:
I replaced all of the underscores with periods due to the "ugly" 
reactions from the last draft.  Yeah, there isn't a lot of logic behind 
"ugly" and having a different delimiter might make it easier to read, 
but I would suggest sticking with the period for these reasons:
1) Everyone thinks the underscores were ugly.
2) disttag is always at the end, so there is no confusion.
3) except... when it is a 3rd party repository where the reptag is at 
the end.  But that isn't so confusing.
Discuss this if you want, but be prepared for more whining about "ugly!"
XXX

C-5. Special Case: Kernel modules
---------------------------------
XXX:
This section still needs much discussion.  Later.
XXX

C-6. Plugin, theme etc packages
-------------------------------
Packages that are plugins, themes or the like, ie. enhance other 
packages must be named <package-to-enhance>-<enhancement>.  If the 
resulting name differs significantly from upstream naming, a
Provides: <upstream-name> = %{epoch}:%{version}-%{release}
must be added.  For example:

Upstream package name: modplug-xmms
Fedora package name:   xmms-modplug
Provides:              modplug-xmms = %{epoch}:%{version}-%{release}

XXX:
Should we actively discourage packages that *appear* to be plugin, 
add-on or theme packages but are actually completely independent?  One 
example that has caught me off guard lately was Dag's mozilla-firebird 
package.  While Dag published mozilla-firebird, fedora.us decided 
against a name change from MozillaFirebird to mozilla-firebird for these 
reasons:
1) No reason to change.
2) Mozilla branding strategy document said the name was changing "soon" 
anyway, (which still hasn't happened.)
3) mozilla-firebird is within the long implicitly understood and 
fedora.us codified standard of being a component or add-on to "mozilla", 
which is clearly wrong in this case.
#2 and #3 were the strongest arguments in my opinion.

I can't think of any other past examples off the top of my head, but I 
really want to avoid these kinds of instances in the future if 
possible.  Please express your opinions.
XXX

C-7. Repository Tag
-------------------
Repository tags are appended to the end of %{release} tags for any 
packages not within Fedora Core or Fedora Extras.  FC and FE are 
excluded because Fedora Core should never contain the same %{name} 
package as Fedora Extras, and vice-versa.  All external and 3rd party 
repositories NEED repository tags.  Fedora Alternatives and Fedora 
Legacy are to use rep tags.

Repository Tag for Normal Packages:
     %{X}.%{disttag}.%{reptag}
Where %{X} is the vepoch and %{disttag} is a distribution tag defined in 
C-4, and reptag is an alphanumeric string standardized and unique for a 
repository.

XXX:
The below examples are using theoretical reptags.
XXX

Fedora Legacy: apache for RH7.3
    apache-1.3.27-4.0.7.3.legacy
Fedora Alternatives: Beowulf for FC2
    kernel-2.6.2-3.2.beowulf
    beowulf-pxe-images-2.3-2.2.beowulf
    cluster-foo-libs-1.7-2.2.beowulf
    cluster-foo-tools-1.7-2.2.beowulf
    cluster-foo-devel-1.7-2.2.beowulf
freshrpms:  3rd party packages for FC1
    diradmin-1.5.1-2.1.fr
AtRPMS:     3rd party packages for FC1
    perl-HTML-Tree-3.18-4.1.at
DAG:        3rd party packages for FC1
    distcc-2.11.1-1.1.dag
Livna:      3rd party packages for FC1
    foogame-3.3-3.beta3.1.lvn
    fooutil-2.1-4.1.lvn
    fooapplet-1.0-9.rc4.1.lvn
kde-redhat: 3rd party Uncrippled KDE packages for FC1
    kdebase-3.1.4-7.1.kderedhat

Note that it is the 3rd party or Alternatives choice of what %{X} number 
to use.  If they use the same %{X} number as the canonical FC/FE 
packages they are superceding, then any future upgrade upstream is 
guaranteed to superceed the 3rd party or Alternatives package.  This can 
be desired or not.


XXX:
The 3 points below need to be worked into the document above 
somewhere... too tired to do that at the moment... discuss for now.

Caveats!
1) Fedora Core and Fedora Extras are to be considered canonical.  All 
other repositories must respect the vepoch of the canonical 
repositories, however FC and FE may choose to ignore 3rd parties when 
incrementing the vepoch for a new package release.
1a) Since fedora.us will eventually become a major source of Fedora 
Extras, fedora.us is to be considered canonical.  fedora.us will no 
longer exist as a project after the full merge with fedora.redhat.com.
2) In the kde-redhat example, since they are a 3rd party and not 
canonical, it is possible that a future FC or FE upgrade will supercede 
the kde-redhat package.  For this reason it is important for kde-redhat 
developers to BE INVOLVED in FC development so they are not caught off 
guard.  It is the 3rd party's responsibility to simultaneously release 
updates to the 3rd party repository in order to avoid breakage or losing 
features when the crippled packages overrides the kde-redhat package.
3) These guidelines of canonism may seem onerous, however this 
encourages all 3rd party developers to contribute their packages to FC 
and FE whenever possible in order to make the central authoritative body 
strong.  I would assert that the alliances of 3rd party repositories 
that have tried to form in the recent past are not sustainable in the 
long term, for the same controversial reasons that fedora.us rejected 
cooperation with those entities earlier this year.  More cooperation is 
needed to build an entity and software base like Debian, what we want to 
become. (?)

XXX





[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]