pk3 versioning guidelines

Post all of your progress here about official assets, and receive feedback from our team.
Post Reply
User avatar
Viech
Project Head
Posts: 2139
Joined: Fri Aug 03, 2012 11:50 pm UTC
Location: Berlin

pk3 versioning guidelines

Post by Viech »

Sharing temporary pk3 files

When sharing pk3 files that are not supposed to be standalone files of the game installation, please use one of the following two formats, so that it will be easier for others to find out the latest version:

  • nameyear-month-day-time.pk3

  • name_year-month-day-time-author.pk3



The date and time is the time when you package the pk3 and uses the following format:

  • year: <2000-2100>

  • month: <01-12>

  • day: <01-31>

  • time: <00-24><00-59> (hour and minute, in GMT/UTC)

  • author: Nickname as lowercase alphanumeric



For example:

  • drill_2014-05-29-1527.pk3

  • drill_2014-05-29-1527-viech.pk3



In case you're having issues with UTC: If your time zone's offset is positive, substract it, otherwise add it (e.g. 20:00 UTC+2 = 18:00 UTC; 20:00 UTC-6 = 02:00 UTC of the next day). Keep local daylight saving in mind. If you're using the 12 hour time format read here.

The reason for using this time format is that it can be sorted by using lexicographical order and is still human readable (as opposed to the unix timestamp, which also isn't easily available for windows users).


Sharing preview versions of standalone pk3 files

For pk3 files that are to be included with the release, for example maps and texture packages, there are two scenarios. If you are the main author of the package in question and it is unlikely that others will want to release a version of their own, you can use the following format:

  • name_targetversion~counter.pk3



For example:

  • map-spacetracks_1.01.pk3



The "~" tells the engine that the pk3 is to be ordered before the specified target version. For example, "tex-common_1.01.pk3" will be considered older than "tex-common_1.02.pk3" which in turn will be considered older than "tex-common_1.0.pk3", so the target release will always overwrite any preview version.

If you are not the only regular author of the pk3 in question, please use the date & time format above instead of the counter:

  • nametargetversion~year-month-day-time.pk3

  • name_targetversion~year-month-day-time-author.pk3



For example:

  • unvanqushed_0.28.02014-05-29-1637.pk3

  • unvanqushed_0.28.02014-05-29-1637-viech.pk3




Releasing fixes to standalone pk3 files

If you are not the main author of a pk3 but want to release a version with additions or bugfixes, use "+" instead of "~" to order your version after the regular release:

  • name_currentversion+counter.pk3



For example:

  • map-spacetracks_1.0+1.pk3



Here "1.0" was the author's original release and "+1" was added to mark an update without interfering with the author's versioning scheme.

Responsible for: Arch Linux package & torrent distribution, Parpax (map), Chameleon (map texture editor), Sloth (material file generator), gameplay design & programming, artistic direction

User avatar
Ishq
Project Head
Posts: 1145
Joined: Tue Mar 06, 2012 8:32 pm UTC

Re: pk3 versioning guidelines

Post by Ishq »

Code: Select all

#!/bin/bash
if [[ -z $1 || ! -d $1 ]]; then
        echo "Not a directory!"
        exit 1
fi
BASE=$(basename $1)
NOW=$(date -u +"%Y-%m-%d-%H-%M")
FILENAME="$(echo $BASE | sed 's/_.*//')_$NOW"
zip -r9 "$FILENAME.pk3" $1
User avatar
Viech
Project Head
Posts: 2139
Joined: Fri Aug 03, 2012 11:50 pm UTC
Location: Berlin

Re: pk3 versioning guidelines

Post by Viech »

You should be zipping the folder's content though, not the folder itself.

Responsible for: Arch Linux package & torrent distribution, Parpax (map), Chameleon (map texture editor), Sloth (material file generator), gameplay design & programming, artistic direction

User avatar
Ishq
Project Head
Posts: 1145
Joined: Tue Mar 06, 2012 8:32 pm UTC

Re: pk3 versioning guidelines

Post by Ishq »

Ah, thanks!

Code: Select all

#!/bin/bash
if [[ -z $1 || ! -d $1 ]]; then
        echo "Not a directory!"
        exit 1
fi
CDIR=$(pwd);
BASE=$(basename $1)
NOW=$(date -u +"%Y-%m-%d-%H-%M")
FILENAME="$(echo $BASE | sed 's/_.*//')_$NOW"
cd "$1"
zip -r9 "$CDIR/$FILENAME.pk3" *
cd "$CDIR"
Post Reply