Create a gist now

Instantly share code, notes, and snippets.

Embed
What would you like to do?
version number evolution discussions from Lyon 2014
Broad decisions about rationalizing version object behavior based on
discussions at the Lyon QAH. Participants: David Golden, Ricardo Signes,
Karen Etheridge, Leon Timmermans, Peter Rabbitson and Graham Knop
- version comparision should be done irrespective of the presence of
underscores in the string used to initialize the version object
- underscore should no longer be used as a tuple separator in vstrings or
vstring-like strings; vstrings are converted to tuples by splitting into
*characters* (not bytes) and converting to codepoints; any elements after
the first must be in the range 0-999
- numify/normal should produce a standarized string representation without
underscores
- stringify should produce the best possible representation of the value
used to initialize the version object; it should include underscores
only if the initializing value was a non-vstring string.
- floating point numbers used as initializers are converted to a decimal
string form at the precision limit of the architecture; people will be
warned about this in the documentation
Examples:
Comparison:
- version->new(1.0203) == version->new("1.0203")
- version->new(1.02_03) == version->new("1.02_03")
- version->new(v1.2.3) == version->new("v1.2.3")
- version->new(v1.2.3_0) == version->new("v1.2.3_0")
Underscore no longer tuple separator:
- version->new(v1.2.3_0) -> tuple (1,2,30)
- version->new("v1.2.3_0") -> tuple (1,2,30)
Numify/normalize don't produce underscore:
- version->new("1.0203")->numify -> "1.0203"
- version->new("1.0203")->normal -> "v1.20.300"
- version->new("1.02_03")->numify -> "1.0203"
- version->new("1.02_03")->normal -> "v1.20.300"
- version->new("v1.2.30")->numify -> "1.002030"
- version->new("v1.2.30")->normal -> "v1.2.30"
- version->new("v1.2.3_0")->numify -> "1.002030"
- version->new("v1.2.3_0")->normal -> "v1.2.30"
Stringify should attempt to preserve string initializers:
- version->new("1.0203")->stringify -> "1.0203"
- version->new("1.02_03")->stringify -> "1.02_03"
- version->new("v1.2.30")->stringify -> "v1.2.30"
- version->new("v1.2.3_0")->stringify -> "v1.2.3_0"
- version->new(1.0203)->stringify -> "1.0203"
- version->new(1.02_03)->stringify -> "1.0203"
- version->new(v1.2.30)->stringify -> "v1.2.30"
- version->new(v1.2.3_0)->stringify -> "v1.2.30"
@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost Mar 15, 2014

Another other thing I wonder about is whether "numify" should have a
minimum decimal length (e.g. padding with zeros on the right when
necessary).

Owner

ghost commented Mar 15, 2014

Another other thing I wonder about is whether "numify" should have a
minimum decimal length (e.g. padding with zeros on the right when
necessary).

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost Mar 15, 2014

we also talked about deprecating is_alpha

Owner

ghost commented Mar 15, 2014

we also talked about deprecating is_alpha

@ribasushi

This comment has been minimized.

Show comment
Hide comment
@ribasushi

ribasushi Mar 15, 2014

Just want to throw a couple of comments attached to the above:

  • There was no significant discussion of the status of _'s in a distname as 'no_index' flags, and the current status quo in this regard is unchanged.
  • There is broad agreement to make no significant efforts to preserve _ during runtime (also see the table above), however tools performing static analysis are still expected to preserve their current logic (with all heuristic as is).

ribasushi commented Mar 15, 2014

Just want to throw a couple of comments attached to the above:

  • There was no significant discussion of the status of _'s in a distname as 'no_index' flags, and the current status quo in this regard is unchanged.
  • There is broad agreement to make no significant efforts to preserve _ during runtime (also see the table above), however tools performing static analysis are still expected to preserve their current logic (with all heuristic as is).
@ribasushi

This comment has been minimized.

Show comment
Hide comment
@ribasushi

ribasushi Mar 15, 2014

As an aside - what the above doesn't seem to cover for me is the sanity of keeping the ->normal semantic broken (i.e. s/_/./). I did not see a case where breaking the normal() behavior will result in any extra breakage on top of everything else.

ribasushi commented Mar 15, 2014

As an aside - what the above doesn't seem to cover for me is the sanity of keeping the ->normal semantic broken (i.e. s/_/./). I did not see a case where breaking the normal() behavior will result in any extra breakage on top of everything else.

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost Mar 15, 2014

@ribasushi, I think github markdown ate some of your comments, but my reactions nonetheless:

  • We're only discussing behavior of version.pm (and by implication, UNIVERSAL::VERSION) and so distribution names are outside the scope. We did say that stringification should attempt to preserve underscores in quoted versions so that other external tools that do have semantics for "_" can make use of them.
  • I don't think "tools performing static analysis" is a correct term. Can you give an example of what you mean? (If you mean does MM->parse_version return "1.02_03" when our $VERSION = "1.02_03", then I concur.
  • On "normal", we currently have an issue where version->parse("1.02_03")->normal is broken. JPEACOCK "fixed" it by making that fatal. We don't want "_" to be a tuple separator, and it's tricky to figure out how to represent in a round-trippable way. 1.2_3 can be v1.2_30.0 but 1.234_567 can't be v1.234_567 because we don't want underscore as a tuple separator. v1.234_.567 is a legal v-string, but looks quite odd. By having normal never keep the underscore, 1.234_567 can numify to 1.234567, normalize to v1.234.567 and stringify to 1.234_567 as it was originally. Does that answer the question?
Owner

ghost commented Mar 15, 2014

@ribasushi, I think github markdown ate some of your comments, but my reactions nonetheless:

  • We're only discussing behavior of version.pm (and by implication, UNIVERSAL::VERSION) and so distribution names are outside the scope. We did say that stringification should attempt to preserve underscores in quoted versions so that other external tools that do have semantics for "_" can make use of them.
  • I don't think "tools performing static analysis" is a correct term. Can you give an example of what you mean? (If you mean does MM->parse_version return "1.02_03" when our $VERSION = "1.02_03", then I concur.
  • On "normal", we currently have an issue where version->parse("1.02_03")->normal is broken. JPEACOCK "fixed" it by making that fatal. We don't want "_" to be a tuple separator, and it's tricky to figure out how to represent in a round-trippable way. 1.2_3 can be v1.2_30.0 but 1.234_567 can't be v1.234_567 because we don't want underscore as a tuple separator. v1.234_.567 is a legal v-string, but looks quite odd. By having normal never keep the underscore, 1.234_567 can numify to 1.234567, normalize to v1.234.567 and stringify to 1.234_567 as it was originally. Does that answer the question?
@ribasushi

This comment has been minimized.

Show comment
Hide comment
@ribasushi

ribasushi Mar 15, 2014

To summarize the outcome of the discussion: we need to say in the docs something to the effect of

"->normal should not be used by anyone besides packagers, and packagers should not be using anything other than version->new($ver)->normal"

Thanks @dagolden for clarifying stuff, @ribasushi is reasonably happy.

ribasushi commented Mar 15, 2014

To summarize the outcome of the discussion: we need to say in the docs something to the effect of

"->normal should not be used by anyone besides packagers, and packagers should not be using anything other than version->new($ver)->normal"

Thanks @dagolden for clarifying stuff, @ribasushi is reasonably happy.

@Leont

This comment has been minimized.

Show comment
Hide comment
@Leont

Leont Jul 17, 2015

stringify should produce the best possible representation of the value used to initialize the version object; it should include underscores only if the initializing value was a non-vstring string.

I do not remember the rationale behind this, and it doesn't make sense to me right now. Why did we want to threat vstrings special? It makes more sense to me to have the closest to the original representation.

Leont commented Jul 17, 2015

stringify should produce the best possible representation of the value used to initialize the version object; it should include underscores only if the initializing value was a non-vstring string.

I do not remember the rationale behind this, and it doesn't make sense to me right now. Why did we want to threat vstrings special? It makes more sense to me to have the closest to the original representation.

@haarg

This comment has been minimized.

Show comment
Hide comment
@haarg

haarg Jul 18, 2015

I'm pretty sure the rationale is to remove the reliance on v-string magic, so it could hopefully be removed in the future. v-strings already ignore underscores for their string component. I suspect @dagolden may be able to confirm that.

haarg commented Jul 18, 2015

I'm pretty sure the rationale is to remove the reliance on v-string magic, so it could hopefully be removed in the future. v-strings already ignore underscores for their string component. I suspect @dagolden may be able to confirm that.

@haarg

This comment has been minimized.

Show comment
Hide comment
@haarg

haarg Oct 21, 2015

@Leont also I believe that sentence is badly worded. It's trying to distinguish between quoted strings and v-string literals. We want to preserve underscores in all forms of quoted strings, but not in v-string literals, as the examples show. This isn't making vstrings special, but putting them on equal ground with numeric forms. version->new(v1.2.3_0) won't preserve the underscore, just like version->new(1.02_03) doesn't.

haarg commented Oct 21, 2015

@Leont also I believe that sentence is badly worded. It's trying to distinguish between quoted strings and v-string literals. We want to preserve underscores in all forms of quoted strings, but not in v-string literals, as the examples show. This isn't making vstrings special, but putting them on equal ground with numeric forms. version->new(v1.2.3_0) won't preserve the underscore, just like version->new(1.02_03) doesn't.

@JohnPeacock

This comment has been minimized.

Show comment
Hide comment
@JohnPeacock

JohnPeacock Jan 2, 2016

The proposed patch has been integrated into 0.9912_01 and thence to 0.9913 except for the limitation "any elements after the first must be in the range 0-999". For one thing, for dotted decimal versions (either quoted or bare v-string), any leading zeros are not significant and will just be ignored when parsing (so 1.2.0000003 => v1.2.3). The other thing is that the current code does not enforce the 3 digit limit for subsequent elements. That can be considered a TODO for now.

JohnPeacock commented Jan 2, 2016

The proposed patch has been integrated into 0.9912_01 and thence to 0.9913 except for the limitation "any elements after the first must be in the range 0-999". For one thing, for dotted decimal versions (either quoted or bare v-string), any leading zeros are not significant and will just be ignored when parsing (so 1.2.0000003 => v1.2.3). The other thing is that the current code does not enforce the 3 digit limit for subsequent elements. That can be considered a TODO for now.

@Leont

This comment has been minimized.

Show comment
Hide comment
@Leont

Leont Jan 3, 2016

stringify should produce the best possible representation of the value used to initialize the version object; it should include underscores only if the initializing value was a non-vstring string.

This is confusing Module::Build, because it no longer recognizes 'v1.2.3_1' as a testing version. See #110882. I have no idea if anyone is actually depending on this, but it does break at least one test. @xdg: opinion?

Leont commented Jan 3, 2016

stringify should produce the best possible representation of the value used to initialize the version object; it should include underscores only if the initializing value was a non-vstring string.

This is confusing Module::Build, because it no longer recognizes 'v1.2.3_1' as a testing version. See #110882. I have no idea if anyone is actually depending on this, but it does break at least one test. @xdg: opinion?

@haarg

This comment has been minimized.

Show comment
Hide comment
@haarg

haarg Jan 4, 2016

My understanding is that 'v1.2.3_1' will still be seen as alpha, but v1.2.3_1 will not. The quoting being the important distinction.

haarg commented Jan 4, 2016

My understanding is that 'v1.2.3_1' will still be seen as alpha, but v1.2.3_1 will not. The quoting being the important distinction.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment