Guide to SlackBuilds.org Version Numbers
========================================

For the most part, you should just use upstream's version number.  The
only restriction there is that - (hyhen) characters are not allowed in
Slackware package version numbers. This is a limitation of Slackware's
pkgtools, so it applies to all SlackBuilds, not just SBo ones.

Illegal Characters
------------------

If upstream's version number has a - in it, such as "1.2.3-4", change
it to an underscore (_) and use code like this in the SlackBuild:

VERSION="${VERSION:-1.2.3_4"
SRCVER="$( echo $VERSION | tr - _ )"

The second line could also be written as:

SRCVER="${VERSION//-/_}"

...which is either more readable, or a hideoous abomination, depending
on your background.

Packaging a git/SVN/etc Commit
------------------------------

Sometimes, the software you're packaging doesn't have releases,
or else the latest release can't be packaged because it contains
bugs that have been fixed in a later git/svn/etc revision. If you
have to package a git revision, please don't just use the git commit
(e.g. a912dead). These are annoying because they can't be sorted or
compared. SVN revisions do increase so you can sort or compare them,
but it's still better to use a more informational version number. It's
recommended that you use either:

[version]+[date]_[revision]

...where [version] is the latest release, [date] is the 8-digit ISO
date (YYYYMMDD format), and [revision] is the git/SVN/etc commit,
or else:

[date]_[revision]

...if the upstream project has never done a release.

Examples:

VERSION="1.0+20260829_a912dead"
VERSION="20260829_a912dead"

If you're packaging a git commit, you'll have to either find a URL
for a tarball (see github.txt, gitlab.txt, codeberg.txt), or find a
way to host it on a web server (see hosting.txt).

No Version Number
-----------------

Some projects just don't have a version number. Usually these are
simple "one-off" utilities that Just Work and don't need later
updates (for examples, see system/crc32_simple and audio/alsacap).

The best way to choose a version number for these, if you can't
find a version in any of the files inside the tarball, is just to
take the modification date of the newest file in the archive.
For alsacap, after downloading the source:

$ tar xvf alsacap.tgz
alsacap/alsacap.c
alsacap/alsacap.1
alsacap/alsacap.pod
alsacap/Makefile
alsacap/LICENSE
$ cd alsacap/
$ ls -lt
total 40
-rw-r----- 1 urchlay users 18660 Aug 21  2020 alsacap.c
-rw-r----- 1 urchlay users  7795 Apr  4  2013 alsacap.1
-rw-r----- 1 urchlay users  3500 Apr  4  2013 alsacap.pod
-rw-r----- 1 urchlay users   306 Apr  4  2013 Makefile
-rw-r----- 1 urchlay users   784 Apr  4  2013 LICENSE

The newest file is listed first. It's Aug 21, 2020, so the
VERSION for alsacap is 20200821.

Another thing to beware of when packaging a tarball without a
version in the filename is md5sum mismatches, if upstreams changes the
tarball. This is especially a problem for active projects that provide
only a "project-latest.tar.gz". See download.txt for more information.
