Distinguish version for "old stable"

[ghost]

This is an important issue that aims to resolve the duplicate versions of Customizer in this "old stable" repo and the official fork. The possibility of duplicate versions had gone unnoticed for many months; I finally realized to that possibility when issue #127 was raised earlier.

Justification

This issue would have to be addressed sooner or later, either by interim maintainer (myself) or by future contributors. Since I have realized this already, I decided to take on this issue now. We can't have same versions of similar program that are being maintained separately, which will confuse end users as well.

The proposed solution shall prevent or at least reduce the chances of end users reporting at wrong repo, like issue #120 that was turned out to be so.

Proposed solution 1

Basically, the easiest approach is to revise line 2 in Makefile and change text from echo stable to echo "old stable" like this:

VERSION = 4.1.4 ($(GIT_VERSION))
GIT_VERSION = $(shell $(GIT) rev-parse --short HEAD || echo "old stable")

As a result, the output for command line customizer --version as well as Customizer GUI will show i.e. 4.1.4 (old stable) that can be distinguished easily. In contrast, the official fork will continue to use echo stable that will show i.e. 4.1.4 (stable). But that is not all.

Proposed solution 2

[Secondly], the version shown by the package manager that is based on debian/changelog. Ideally, the version specified here should reflect the version similar to what is shown by the ouput of command line and GUI i.e. 4.1.4 (old stable).

I could distinguish version from "old stable" by adding the suffix -orig or just the revision number -0 to the version in debian/changelog to indicate that package is created from the 'original' repo; According to Debian Policy Manual, the absence of revision number i.e. 4.1.4 is equivalent to with revision number 0 i.e. 4.1.4-0.

customizer (4.1.4-0) unstable; urgency=medium

  * Example change log with modified version for "old stable"

 -- Maintainer Name <[email protected]>  Fri, 23 Sep 2016 12:46:08 +0800

As a result, the created Debian package will be named as customizer_4.1.4-0_all.deb (Tested working using dummy source package; The suffix -0 is preserved, which I initially thought it would be trimmed by debhelper, since documentation claimed "is equivalent").

In contrast, the official fork will continue to generate customizer_4.1.4_all.deb. Even better, the official fork should add unique suffix to clearly distinguish itself from the original repo as well as other forks. In other words, customizer_4.1.4-kamilion_all.deb is better than without the fork owner name (This should be suggested as new issue in the official fork anyway).

Proposed solution 3

[Thirdly], the source package (.zip, .tar.gz) is named neither with the word -orig nor the revision number -0! Aside from the GitHub code repository page, links to download source packages are found in releases and tags pages. Upon clicking one of these links to respective package, the download dialog will show REPONAME-TAG.tar.gz i.e. "Customizer-4.1.4.tar.gz".

Therefore, tags might be better renamed to contain revision number -0 for "old stable" repo. This shall be applied from patch release 4.1.2, which is the first distinguished release since the official fork has been created. To apply the solutions appropriately, there is a need to:

• create new tag and release with revision number i.e. 4.1.2-0, 4.1.3-0
• include additional note for above changes
• delete old tag without revision number i.e. 4.1.2, 4.1.3
• 4.1.2 and 4.1.3 are limited to proposed solution 3 only (done on the same day as this)
• 4.1.4 and onwards shall include all proposed solutions

Proposed solutions are effective from 4.1.4 and onwards, while limited for 4.1.2 and 4.1.3.

[ghost]

The first proposed solution has been implemented in master branch. The output for command line customizer --version as well as Customizer GUI will now show 4.1.3 (old stable).

[ghost]

Extended explanation for Proposed solution 2.

There is one discrepancy that remain in this solution. While package content may be updated from time to time in the repository on GitHub, this isn't reflected by the package version i.e. X.Y.Z-0. For this reason, I have researched on how other suffixes - + ~ are used in package versioning.

To this date, there is no one-stop documentation that explains all possible patterns. So I had to do cross-reference and refine my searching keywords for few times. The following are relevant links.

• Control files and their fields in Debian Policy Manual
• 5.11.2. NMUs and debian/changelog in Debian Developer's Reference
• ubuntu - debian packages version convention on Server Fault
• What is the meaning of the tilde in some debian openjdk package version string? on Unix & Linux Stack Exchange
• What do '+b#' packages versions mean in Debian? on Unix & Linux Stack Exchange

Based on above references, I would like to extend the proposed solution with additional suffix +YYYYMMDD to indicate latest changes made to version X.Y.Z.

Justification

The extended proposal is actually inspired based on suggested upstream versioning that contain suffix ~YYYYMMDD by one of references that I lost track of. But instead of using tilda ~, I use plus +, which is intuitive and well known symbol for 'addition'.

I have avoided to use suffix . ~ because these are quite confusing for end users.

• The period . is likely familiar to most users, being just the extension of existing version. For example, hello-1.0.1 is higher version than hello-1.0. If we have the additional suffix of debian_revision -1, then hello-1.0-1.1 is higher version than hello-1.0-1.

• The tilda ~ is usually used to indicate testing package version, such as hello-1.0~test1 which is lower version than hello-1.0. If we have the additional suffix of debian_revision -1, then hello-1.0-1~test1 is lower version than hello-1.0-1.

So, when using tilda ~, longer name of package version doesn't necessarily mean latest version. Since we already have proposed debian_revision -0 to indicate "old stable", the period . that comes afterwards i.e. -0.1 will complicate the package version and less useful.

Versioning order

In terms of Debian package versioning order, see the following list (from top: lower version).

4.1.3    <-- before distinguish version for "old stable"
4.1.3-0  <-- this is equivalent to without suffix i.e. 4.1.3
4.1.3-0+20161122
4.1.3-0+20161129
4.1.4-0  <-- this is equivalent to without suffix i.e. 4.1.4
4.1.4-0+YYYYMMDD

Also, to see how tilda influence the package version order, modify debian/changelog and run make deb command to create package, then see the output in Terminal. If the version order is wrong, there will be a warning towards the end of package creation.

...
 dpkg-genchanges -b >../customizer_4.1.3-0~test1_i386.changes
dpkg-genchanges: warning: the current version (4.1.3-0~test1) is earlier than
 the previous one (4.1.3-0)
dpkg-genchanges: binary-only upload - not including any source code
 dpkg-source --after-build Customizer-master
dpkg-buildpackage: binary only upload (no source included)

GUI vs package version

It is important to note that GUI version will always show like X.Y.Z (old stable), while the package version will show like X.Y.Z-0+YYYYMMDD. Both GUI and package versions shall always have the same semantic version X.Y.Z.

Even the package version may have updated version +YYYYMMDD, there will be no changes to GUI version. The only time both GUI and package versions would change together is when the semantic version X.Y.Z is increased.

To illustrate the "old stable" version trend, using dummy versions as example:

GUI version	Package version
4.1.3 (old stable)	4.1.3-0
4.1.3 (old stable)	4.1.3-0+20161017
4.1.3 (old stable)	4.1.3-0+20161109
4.1.3 (old stable)	4.1.3-0+20161120
4.1.4 (old stable)	4.1.4-0
4.1.4 (old stable)	4.1.4-0+20161129

This extended proposal will benefit end users who tend to regularly update the software, such that latest version can be checked via package manager i.e. dpkg --status customizer | grep ^Version.

Date format

YYYYMMDD is the four-digit year, two-digit month and two-digit day, preferably date in Universal Coordinated Time (UTC). The date string is similar to ISO 8601 format, except without the hyphens. This can be generated by running date -u +%Y%m%d in Terminal.

Verdict

Hereby, the fullest package version for "old stable" will be established as X.Y.Z-0+YYYYMMDD and this shall be applicable to current version i.e. 4.1.3.

P.S.: Added Date format for information.

[ghost]

Test current version

Latest source has been downloaded, compiled and installed via package manager. The following output are showing the fullest package version for "old stable" via dpkg i.e. X.Y.Z-0+YYYYMMDD, while CLI/GUI version remain to use semantic version i.e. X.Y.Z.

$ dpkg --status customizer | grep ^Version
Version: 4.1.3-0+20161130

$ customizer --version
* Read Configuration file: /etc/customizer.conf
Customizer 4.1.3 (old stable)

Test future version (simulation)

When debian/changelog is modified in the future:

customizer (4.1.4-0) unstable; urgency=medium

  * Test future version

 -- Testing <[email protected]>  Wed, 30 Nov 2016 23:54:04 +0800

customizer (4.1.3-0+20161130) unstable; urgency=medium

  * Added suffix '-0' to indicate "old stable"
  * Added suffix '+YYYYMMDD' to indicate latest changes to version X.Y.Z
  * Enhanced debian/copyright. Fixes: #143 B.
  * Updated description in debian/control. Fixes: #146 A.

 -- Testing <[email protected]>  Wed, 30 Nov 2016 13:16:12 +0000

customizer (4.1.3-0+20161120) unstable; urgency=medium

  * Testing package version with suffix '-0+YYYYMMDD'

 -- Testing <[email protected]>  Sun, 20 Nov 2016 02:00:14 +0000

Then, run make deb to create Debian package:

$ cd Customizer-master/ && make deb && cd ..
DEB_BUILD_OPTIONS=nocheck dpkg-buildpackage -us -uc -b
dpkg-buildpackage: source package customizer
dpkg-buildpackage: source version 4.1.4-0
dpkg-buildpackage: source distribution unstable
...
 dpkg-genchanges -b >../customizer_4.1.4-0_i386.changes
dpkg-genchanges: binary-only upload - not including any source code
 dpkg-source --after-build Customizer-master
dpkg-buildpackage: binary only upload (no source included)

$ ls -1 *.deb *.changes
customizer_4.1.4-0_all.deb
customizer_4.1.4-0_i386.changes

Therefore, test above proves that 4.1.3-0+20161130 or any similar version will be successfully replaced by future version 4.1.4-0 and so forth.

Following successful results by testing both current and future versions, this issue has been confirmed 'implemented' and shall be closed.