// vim:set filetype=asciidoc:
[[name-version]]
=== Package name and version

If the upstream source comes as *hello-0.9.12.tar.gz*, you can take *hello* as the upstream source package name and *0.9.12* as the upstream version.

include::caveat-version.txt[]

You must adjust the package name and upstream version accordingly for the Debian packaging.

In order to manage the package name and version information effectively under popular tools such as the *aptitude* command, it is a good idea to keep the length of package name to be equal or less than 30 characters; and the total length of version and revision to be equal or less than 14 characters. footnote:[For more than 90% of packages, the package name is equal or less than 24 characters; the upstream version is equal or less than 10 characters and the Debian revision is equal or less than 3 characters.]

In order to avoid name collisions, the user visible binary package name should not be chosen from any generic words.

// aptitude bug #62454 fixed :-)

If upstream does not use a normal versioning scheme such as *2.30.32* but uses some kind of date such as *11Apr29*, a random codename string, or a VCS hash value as part of the version, make sure to remove them from the upstream version. Such information can be recorded in the *debian/changelog* file. If you need to invent a version string, use the *YYYYMMDD* format such as *20110429* as upstream version. This ensures that the *dpkg* command interprets later versions correctly as upgrades. If you need to ensure a smooth transition to a normal version scheme such as *0.1* in the future, use the *0~YYMMDD* format such as *0~110429* as upstream version, instead.

Version strings can be compared using the *dpkg* command as follows.

----
$ dpkg --compare-versions ver1 op ver2
----

The version comparison rule can be summarized as:

* Strings are compared from the head to the tail.
* Letters are larger than digits.
* Numbers are compared as integers.
* Letters are compared in ASCII code order.

There are special rules for period (*.*), plus (*+*), and tilde (*~*) characters, as follows.

----
0.0 < 0.5 < 0.10 < 0.99 < 1 < 1.0~rc1 < 1.0 < 1.0+b1 < 1.0+nmu1 < 1.1 < 2.0
----

One tricky case occurs when the upstream releases *hello-0.9.12-ReleaseCandidate-99.tar.gz* as the pre-release of *hello-0.9.12.tar.gz*. You can ensure the Debian package upgrade to work properly by renaming the upstream source to *hello-0.9.12~rc99.tar.gz*.

[[native]]
=== Native Debian package

The non-native Debian package in the Debian source format "`**3.0 (quilt)**`" is the most normal Debian source package format.  The *debian/source/format* file should have "`**3.0 (quilt)**`" in it as described in *dpkg-source*(1).  The above workflow and the following packaging examples always use this format.

A native Debian package is the rare Debian binary package format.  It may be used only when the package is useful and valuable only for Debian.  Thus, its use is generally discouraged.

CAUTION: A native Debian package is often accidentally built when its upstream tarball is not accessible from the *dpkg-buildpackage* command with its correct name __package_version__.*orig.tar.gz* .  This is a typical newbie mistake caused by making a symlink name with "`**-**`" instead of the correct one with "`**_**`".

A native Debian package has no separation between the *upstream code* and the *Debian changes* and consists only of the following:

* __package_version__**.tar.gz** (copy or symlink of __package-version__**.tar.gz** with *debian/** files.)
* __package_version__**.dsc**

If you need to create a native Debian package, create it in the Debian source format "`**3.0 (native)**`" using *dpkg-source*(1).

TIP: There is no need to create the tarball in advance if the native Debian package format is used. The *debian/source/format* file should have "`**3.0 (native)**`" in it as described in *dpkg-source*(1) and The *debian/source/format* file should have the version without the Debian revision (*1.0* instead of *1.0-1*). Then, the tarball containing is generated when "`*dpkg-source -b*`" is invoked in the source tree.
