Skip to content

Commit 4d7d6ae

Browse files
rhansenrhansen
authored
Merge pull request ddclient#777 from rhansen/semver
Use semver 2.0.0 as the human-readable version string format
2 parents 9f2d627 + 54b6d0c commit 4d7d6ae

File tree

3 files changed

+57
-42
lines changed

3 files changed

+57
-42
lines changed

‎ChangeLog.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
This document describes notable changes. For details, see the [source code
44
repository history](https://github.com/ddclient/ddclient/commits/main).
55

6-
## v4.0.0~alpha (unreleased work-in-progress)
6+
## v4.0.0-alpha (unreleased work-in-progress)
77

88
### Breaking changes
99

‎ddclient.in

+32-17
Original file line numberDiff line numberDiff line change
@@ -36,25 +36,40 @@ use Sys::Hostname;
3636
# Note that version::normal and version::numify lose information because the underscore is
3737
# effectively removed.
3838
#
39-
# To work around Perl's limitations, human-readable versions are translated to/from Perl versions
40-
# as follows:
39+
# To work around Perl's limitations, Perl versions are translated to/from human-readable Semantic
40+
# Versioning 2.0.0 <https://semver.org/spec/v2.0.0.html> version strings as follows:
4141
#
4242
# Human-readable Perl version Notes
4343
# -------------------------------------------------------------------------------------------
44-
# 1.2.3~alpha v1.2.3.0_0 compares equal to Perl version v1.2.3 (unfortunately)
45-
# 1.2.3~betaN v1.2.3.0_N 1 <= N < 900; compares equal to Perl v1.2.3.N
46-
# 1.2.3~rcN v1.2.3.0_M 1 <= N < 99; M = N + 900; compares equal to Perl v1.2.3.M
44+
# 1.2.3-alpha v1.2.3.0_0 compares equal to Perl version v1.2.3 (unfortunately)
45+
# 1.2.3-beta.N v1.2.3.0_N 1 <= N < 900; compares equal to Perl v1.2.3.N
46+
# 1.2.3-rc.N v1.2.3.0_M 1 <= N < 99; M = N + 900; compares equal to Perl v1.2.3.M
4747
# 1.2.3 v1.2.3.999 for releases; no underscore in Perl version string
48-
# 1.2.3rN v1.2.3.999.N 1 <= N < 1000; for re-releases, if necessary (rare)
48+
# 1.2.3+r.N v1.2.3.999.N 1 <= N < 1000; for re-releases, if necessary (rare)
4949
#
50-
# A tilde is used to separate "alpha", "beta", and "rc" from the version numbers because it has
51-
# special meaning for the version comparison algorithms in RPM and Debian:
52-
# https://docs.fedoraproject.org/en-US/packaging-guidelines/Versioning/#_handling_non_sorting_versions_with_tilde_dot_and_caret
53-
# https://manpages.debian.org/bookworm/dpkg-dev/deb-version.7.en.html
50+
# A hyphen-minus ('-', a.k.a. dash) is used to separate "alpha", "beta", and "rc" from the version
51+
# numbers because that is what <https://semver.org/spec/v2.0.0.html> requires. Tilde ('~') was
52+
# considered instead of '-' because it has desirable semantics in the version comparison algorithms
53+
# in Debian and RPM; see <https://manpages.debian.org/bookworm/dpkg-dev/deb-version.7.en.html> and
54+
# <https://docs.fedoraproject.org/en-US/packaging-guidelines/Versioning/#_handling_non_sorting_versions_with_tilde_dot_and_caret>
55+
# However, tilde is not permitted in Git tags, so the human-readable version string would have to
56+
# be transformed for release tags, and then transformed back by downstream package maintainers to
57+
# reconstruct the original version string. As long as downstream package maintainers have to
58+
# transform the tag name anyway, the human-readable version string might as well have the same
59+
# format as the tag name. Version strings conforming to <https://semver.org/spec/v2.0.0.html> have
60+
# this property.
5461
#
55-
# No period separator is required between "beta", "rc", or "r" and its adjacent number(s); both RPM
56-
# and Debian will compare the adjacent number numerically, not lexicographically ("~beta2" sorts
57-
# before "~beta10" as expected).
62+
# A period is required between "beta" or "rc" and its adjacent number(s) because
63+
# <https://semver.org/spec/v2.0.0.html> says that parts containing non-number characters are
64+
# compared lexicographically. For example, '-beta9' unfortunately sorts after '-beta10' but
65+
# '-beta.9' sorts before '-beta.10', as desired. (Both the Debian and the RPM version comparison
66+
# algorithms do not have this problem; they compare number parts numerically, not
67+
# lexicographically, even if there is no period between the number and non-number characters.)
68+
#
69+
# A period is also required after the "r" for a re-release, but this is only for consistency with
70+
# "beta" and "rc". <https://semver.org/spec/v2.0.0.html> says that build metadata (the stuff after
71+
# the plus ('+') character) does not affect ordering at all so the lack of a period would not
72+
# affect ordering.
5873
#
5974
# The Perl version is declared first then converted to a human-readable form. It would be nicer to
6075
# declare a human-readable version string and convert that to a Perl version string, but various
@@ -88,13 +103,13 @@ sub humanize_version {
88103
return $v if !defined($r);
89104
$v = $r;
90105
if (!defined($pr)) {
91-
$v .= "r$rr" if defined($rr);
106+
$v .= "+r.$rr" if defined($rr);
92107
} elsif ($pr eq '0') {
93-
$v .= '~alpha';
108+
$v .= '-alpha';
94109
} elsif ($pr < 900) {
95-
$v .= "~beta$pr";
110+
$v .= "-beta.$pr";
96111
} elsif ($pr < 999) {
97-
$v .= '~rc' . ($pr - 900);
112+
$v .= '-rc.' . ($pr - 900);
98113
}
99114
return $v;
100115
}

‎t/version.pl.in

+24-24
Original file line numberDiff line numberDiff line change
@@ -8,33 +8,33 @@ ok(ddclient::parse_version($ddclient::VERSION),
88
"module's Perl version string is in opinionated form");
99

1010
my $n = qr/0|[1-9]\d{0,2}/;
11-
like($ddclient::version, qr/^$n\.$n\.$n(?:~alpha|~beta$n|~rc$n|r$n)?$/,
11+
like($ddclient::version, qr/^$n\.$n\.$n(?:-alpha|-beta\.$n|-rc\.$n|\+r\.$n)?$/,
1212
"human-readable version is in opinionated form");
1313

1414
my @tcs = (
15-
['v1.0_0', '1~alpha'],
16-
['v1.0.0_0', '1.0~alpha'],
17-
['v1.2.3.0_0', '1.2.3~alpha'],
18-
['v1.2.3.4.0_0', '1.2.3.4~alpha'],
19-
['v1.0_1', '1~beta1'],
20-
['v1.0.0_1', '1.0~beta1'],
21-
['v1.2.3.0_1', '1.2.3~beta1'],
22-
['v1.2.3.4.0_1', '1.2.3.4~beta1'],
23-
['v1.2.3.0_899', '1.2.3~beta899'],
24-
['v1.0_901', '1~rc1'],
25-
['v1.0.0_901', '1.0~rc1'],
26-
['v1.2.3.0_901', '1.2.3~rc1'],
27-
['v1.2.3.4.0_901', '1.2.3.4~rc1'],
28-
['v1.2.3.0_998', '1.2.3~rc98'],
15+
['v1.0_0', '1-alpha'],
16+
['v1.0.0_0', '1.0-alpha'],
17+
['v1.2.3.0_0', '1.2.3-alpha'],
18+
['v1.2.3.4.0_0', '1.2.3.4-alpha'],
19+
['v1.0_1', '1-beta.1'],
20+
['v1.0.0_1', '1.0-beta.1'],
21+
['v1.2.3.0_1', '1.2.3-beta.1'],
22+
['v1.2.3.4.0_1', '1.2.3.4-beta.1'],
23+
['v1.2.3.0_899', '1.2.3-beta.899'],
24+
['v1.0_901', '1-rc.1'],
25+
['v1.0.0_901', '1.0-rc.1'],
26+
['v1.2.3.0_901', '1.2.3-rc.1'],
27+
['v1.2.3.4.0_901', '1.2.3.4-rc.1'],
28+
['v1.2.3.0_998', '1.2.3-rc.98'],
2929
['v1.999', '1'],
3030
['v1.0.999', '1.0'],
3131
['v1.2.3.999', '1.2.3'],
3232
['v1.2.3.4.999', '1.2.3.4'],
33-
['v1.999.1', '1r1'],
34-
['v1.0.999.1', '1.0r1'],
35-
['v1.2.3.999.1', '1.2.3r1'],
36-
['v1.2.3.4.999.1', '1.2.3.4r1'],
37-
['v1.2.3.999.999', '1.2.3r999'],
33+
['v1.999.1', '1+r.1'],
34+
['v1.0.999.1', '1.0+r.1'],
35+
['v1.2.3.999.1', '1.2.3+r.1'],
36+
['v1.2.3.4.999.1', '1.2.3.4+r.1'],
37+
['v1.2.3.999.999', '1.2.3+r.999'],
3838
[$ddclient::VERSION, $ddclient::version],
3939
);
4040

@@ -49,10 +49,10 @@ subtest 'human-readable version can be translated back to Perl version' => sub {
4949
for my $tc (@tcs) {
5050
my ($want, $hv) = @$tc;
5151
my $pv = "v$hv";
52-
$pv =~ s/^(?!.*~)(.*?)(?:r(\d+))?$/"$1.999" . (defined($2) ? ".$2" : "")/e;
53-
$pv =~ s/~alpha$/.0_0/;
54-
$pv =~ s/~beta(\d+)$/.0_$1/;
55-
$pv =~ s/~rc(\d+)$/'.0_' . (900 + $1)/e;
52+
$pv =~ s/^(?!.*-)(.*?)(?:\+r\.(\d+))?$/"$1.999" . (defined($2) ? ".$2" : "")/e;
53+
$pv =~ s/-alpha$/.0_0/;
54+
$pv =~ s/-beta\.(\d+)$/.0_$1/;
55+
$pv =~ s/-rc\.(\d+)$/'.0_' . (900 + $1)/e;
5656
is($pv, $want, "$hv -> $want");
5757
}
5858
};

0 commit comments

Comments
 (0)