API Change - tidyReleaseDate()

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

API Change - tidyReleaseDate()

Jim Derry
Cross-posted to
 [1]: https://lists.w3.org/Archives/Public/public-htacg/
 [2]: https://sourceforge.net/p/tidy/mailman/tidy-develop
 [3]: https://lists.w3.org/Archives/Public/html-tidy/

Good day all,

This is a request for comments about the treatment of `tidyReleaseDate()`.

HTACG' current proposal and working branch currently is working on the assumption that we will move to a semantic versioning system as a replacement for a date-based version system. This has been implemented on the working branch using `tidyLibraryVersion()` in the API. Our goal is the first 5.0.0-rc.1 by February's end.

While we will deprecate `tidyReleaseDate()` it still has to return a valid date as TidyLib users may be using it. Current development branch returns Unix epoch time (1970/1/1), which we feel should be enough of an indicator to users that the `tidyReleaseDate()` is no longer trustworthy.

I seek your opinions on whether you or anyone you are aware of:

- currently use `tidyReleaseDate()` in a manner that justifies its continued existence and support?
- currently use it in a way that returning Unix epoch would break your application?
- unwilling to make changes to your existing application to support the transition to `tidyLibraryversion()`?
- have a better suggestion for a suitable return value during the deprecation period?

Please comment to any of these lists, or alternative on the [issues tracker][1].

Thank you.


References:
  [1]: https://github.com/htacg/tidy-html5/issues/148


--
---
Jim Derry
Clinton Township, MI, USA
Nanjing, Jiangsu, China PRC
Reply | Threaded
Open this post in threaded view
|

Re: API Change - tidyReleaseDate()

Richard A. O'Keefe

On 10/02/2015, at 3:13 pm, Jim Derry <[hidden email]> wrote:

> Cross-posted to
>  [1]: https://lists.w3.org/Archives/Public/public-htacg/
>  [2]: https://sourceforge.net/p/tidy/mailman/tidy-develop
>  [3]: https://lists.w3.org/Archives/Public/html-tidy/
>
> Good day all,
>
> This is a request for comments about the treatment of `tidyReleaseDate()`.
>
> HTACG' current proposal and working branch currently is working on the assumption that we will move to a semantic versioning system as a replacement for a date-based version system.

There is nothing about a semantic versioning system that forbids you
offering timestamps *as well*.  Release dates and versions are quite
different, indeed, nearly independent things.  (A patched release of an
old version can be released after a new version.)

Suppose a program (I have a particular one in mind) tells you that it
is version 5.9.124867.  What does that actually signify?  Is that a recent
version or an obsolete version?  But when it tells me it was released on
2010/08/11 then I *know* that it is an old version *without having to check
some web site to see what the latest version is*.

> This has been implemented on the working branch using `tidyLibraryVersion()` in the API. Our goal is the first 5.0.0-rc.1 by February's end.
>
> While we will deprecate `tidyReleaseDate()`

Why?  And why should it be untrustworthy?

If I want to answer the question "How likely is it that this version of Tidy might
need updating", a release date is a better clue than a version number.
Especially when your build tools should give you accurate release dates for free!

One thing I will say is that wrong answers are, as a rule, WORSE than no answers.





Reply | Threaded
Open this post in threaded view
|

Re: API Change - tidyReleaseDate()

Jim Derry
One thing I will say is that wrong answers are, as a rule, WORSE than no answers.

That's a good point. The thought was that providing NO answer might break existing functionality in an application that doesn't check that the date is formatted in the same way every time, thus using the Unix epoch to represent "no answer" without breaking an API. If not for this concern we might have simply made the date function a synonym of the version function.

Especially when your build tools should give you accurate release dates for free!

Our build tools are currently capable of giving us a build date right now, which means we could have a version 6.0.0 built in 2015 that would appear newer than a 7.1.2 built in 2014, and so in an of itself isn't meaningful.

It's trivial to update the build date at the same time as the version number so that the previous paragraph doesn't apply, which would be the preferred approach if we decide not to deprecate `tidyReleaseDate()`. That is, it becomes a true "release" data and not a "build date" (as it was using some of the legacy build systems).

I would still argue for the semantic version number in addition to the release date. Do I want the sysadmin to upgrade 25 systems when the version moves from 5.0.0 to 5.0.1? What about to 5.1.0? That implies an API change I have to test for first. Whereas using _only_ a date might mean that there's a two year difference between 5.0.0 and 5.0.1. (Hopefully this situation doesn't come to pass again!)

So the current tally stands as:

1 in favor of keeping both.
0 other responses.

Richard, thanks for the feedback. 


Reply | Threaded
Open this post in threaded view
|

Re: API Change - tidyReleaseDate()

Michael Russell
Deprecating the release date is fine by me, however, I do agree with Richard in that the current API should return an accurate date until it's fully removed from the API. Since there's already concerns brought up on it and it's trivial to keep updated we might has well let it tag along with the new semantic versioning.



On Tue Feb 10 2015 at 8:57:50 PM Jim Derry <[hidden email]> wrote:
One thing I will say is that wrong answers are, as a rule, WORSE than no answers.

That's a good point. The thought was that providing NO answer might break existing functionality in an application that doesn't check that the date is formatted in the same way every time, thus using the Unix epoch to represent "no answer" without breaking an API. If not for this concern we might have simply made the date function a synonym of the version function.

Especially when your build tools should give you accurate release dates for free!

Our build tools are currently capable of giving us a build date right now, which means we could have a version 6.0.0 built in 2015 that would appear newer than a 7.1.2 built in 2014, and so in an of itself isn't meaningful.

It's trivial to update the build date at the same time as the version number so that the previous paragraph doesn't apply, which would be the preferred approach if we decide not to deprecate `tidyReleaseDate()`. That is, it becomes a true "release" data and not a "build date" (as it was using some of the legacy build systems).

I would still argue for the semantic version number in addition to the release date. Do I want the sysadmin to upgrade 25 systems when the version moves from 5.0.0 to 5.0.1? What about to 5.1.0? That implies an API change I have to test for first. Whereas using _only_ a date might mean that there's a two year difference between 5.0.0 and 5.0.1. (Hopefully this situation doesn't come to pass again!)

So the current tally stands as:

1 in favor of keeping both.
0 other responses.

Richard, thanks for the feedback. 


Reply | Threaded
Open this post in threaded view
|

Re: API Change - tidyReleaseDate()

Richard A. O'Keefe
In reply to this post by Jim Derry

On 11/02/2015, at 2:57 pm, Jim Derry <[hidden email]> wrote:
> > Especially when your build tools should give you accurate release dates for free!
>
> Our build tools are currently capable of giving us a build date right now, which means we could have a version 6.0.0 built in 2015 that would appear newer than a 7.1.2 built in 2014, and so in an of itself isn't meaningful.

It is perfectly meaningful.  The whole point I am making is that "release date" and "semantic version"
tell you DIFFERENT things about a program.  It is true that "release date" is an inferior substitute
for "semantic version", just like pepper is an inferior substitute for salt.  As it happens, I never
use pepper, but I wouldn't get away with taking it off the table just because I'd put salt there.

It is also the case that "build date" is not the same as "release date".
If you take an old version and patch it, you have a new release with a new release date.
It also has a new build date.
If you take an old version and DON'T patch it, you have an old release with an old release date.
Recompiling it will give you a new build date, but that's not the same as release date.
>
> I would still argue for the semantic version number in addition to the release date.

Of course.  That's my whole point.  They are (correlated but logically) independent
pieces of information about a program.  It is good to have *both*.

> Do I want the sysadmin to upgrade 25 systems when the version moves from 5.0.0 to 5.0.1? What about to 5.1.0? That implies an API change I have to test for first. Whereas using _only_ a date might mean that there's a two year difference between 5.0.0 and 5.0.1. (Hopefully this situation doesn't come to pass again!)

According to semver.org, in 5.0.1
 - the MAJOR version (5) changes when there are incompatible API changes
 - the MINOR version (0) changes when you add stuff in a compatible way
 - the PATCH version (1) changes when you make "backwards-compatible bug fixes".
Of course, it's not entirely clear what "backwards-compatible bug fixes" are.
If I take a square root function that raises an exception for -0.0 and modify
it to return -0.0 as the IEEE floating point standard requires (that is, so
that when x == 0, sqrt(x) is identical to x), I would normally think of that
as a backwards-compatible bug fix.  If a security hole is closed, I would
normally think of that as a backwards compatible bug fix, and I would like to
see those systems upgraded.

I suppose whether a bug fix counts as backwards-compatible depends on how
strong a specification you have in the interface.  If your specification says
"sqrt(x) raises an exception if x has the sign bit set", then the change about
is not backwards compatible.  If your specifications says "sqrt(x) raises an
exception if x < 0", then the change might count as backwards-compatible.

Here's one way in which a date can be useful and a semantic version not so:
suppose a new security hole is announced, like Heartbleed or POODLE.  If I
know a program was released after the hole was introduced but before it was
closed, it's worth taking some time to find out if there is a new version.
The semantic version number gives me no clue here.  (Actually, this is one
reason why I dislike dynamic linking.  The program may have been perfectly
secure when released, but an update to a library it depends on may have
introduced a security hole.)

I don't think we have a good answer to versioning yet.  Semantic versioning
tries to answer the question "if I wrote for version X and switch to version
Y, is it likely to break".  But of course typical programs these days have
lots of components, some third-party, some dynamically bound, and each of
them has its own version and release information and its own vulnerabilities
and history.  We can hardly fit everything that might be useful into a single
'version number'.

I once did some work on a program where a potential customer had a rigid
policy that _every_ program they bought had to provide its version number
and release date.