allow Dyna to report its own version

[jeisner]

I recommend supporting the traditional GNUish dyna --version, as well as a version command at the repl. Should print git version id and the date of that version (possibly also the build date).

Where do these strings come from? There seems to be a consensus that they should be defined by the makefile at build time (e.g., dumped into a file), rather than by activating git keyword substitution. See http://stackoverflow.com/questions/2696975/how-to-add-revision-and-build-date-to-source and several useful links there.

@nwf wrote on an email thread:

FWIW, the date on the dyna top-level executable is not indicative of the last time of update; that file is just a shell script wrapper around other files in the tree and is not changed by compilation.

You might find "ls -dl which dyna | xargs dirname" or even "ls -ld which dyna | xargs dirname/.git" to be better approximations, but really there's nothing better than something like "(cd which dyna | xargs dirname; git log | grep Date | head -n 1)".

[timvieira]

Not sure it matters, but I'll point out that git log does the wrong thing
if you have uncommitted changes.

On Tue, Jul 23, 2013 at 2:50 AM, Jason Eisner [email protected]:

I recommend supporting the traditional GNUish dyna --version, as well as
a version command at the repl. Should print git version id and the date
of that version (possibly also the build date).

Where do these strings come from? There seems to be a consensus that they
should be defined by the makefile at build time (e.g., dumped into a file),
rather than by activating git keyword substitution. See
http://stackoverflow.com/questions/2696975/how-to-add-revision-and-build-date-to-sourceand several useful links there.

@nwf https://github.com/nwf wrote on an email thread:

FWIW, the date on the dyna top-level executable is not indicative of the
last time of update; that file is just a shell script wrapper around other
files in the tree and is not changed by compilation.

You might find "ls -dl which dyna | xargs dirname" or even "ls -ld which
dyna | xargs dirname/.git" to be better approximations, but really
there's nothing better than something like "(cd which dyna | xargs dirname;
git log | grep Date | head -n 1)".

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/62
.

[timvieira]

Here's what I've got using these commands, which run at the time you ask for them (not by the Makefile).

(cd $DYNAHOME ; grep '^Version' dyna.cabal)
(cd $DYNAHOME ; git log -n 1 |grep '^Date' )
(cd $DYNAHOME ; git log -n 1 |grep '^commit')

Example output:

$ ./dyna --version
Version:        0.4
Date:   Tue Jul 23 00:00:22 2013 -0400
commit 9a7d0d5b7cf7eb6bb0f27b22c58ed4c7c1565529

[jeisner]

Output format looks on the right track, but a few suggestions / concerns:

• You don't want to run the commands at the time you ask for them. That tells you the latest version in the repo rather than the version you are actually running! And it requires you to have a live git checkout, which wouldn't be the case for a packaged version.
• A URL to the repo version might be nice.
• Reporting Version: 0.4 seems misleading because there are many versions that will report that.

Did you look at the StackOverflow links starting at the URL I posted above, which detail how other people have handled this? It's a gold mine. Including "git describe" and "git rev-list" and someone's script at https://gist.github.com/Abizern/208825, not to mention git's own solution ...
(These last were at http://stackoverflow.com/questions/677436/how-to-get-the-git-commit-count/15315094#15315094 .)

[timvieira]

I'm not sure I see any difference in the links you provided (except that they can give a shorter sha1 hash). What am I missing?

Also, feel free to add a target to the Makefile which creates a VERSION file and I'll hook it up.

[timvieira]

Reporting Version: 0.4 seems misleading because there are many versions that will report that.

"0.4" is some number @nwf declared as Dyna's version (e.g. perl5 or Python 2.7). I suppose it doesn't really mean at the time being because we don't have any tagged releases or packaged versions.

If you ask dyna --version and you receive "version: 0.4..." what else could that mean?

[jeisner]

Should look more like this:

$ ./dyna --version
Version: Dyna 0.4 pre-release 477    [or maybe Dyna 0.3.10 rev 477]
Build date: Tue Jul 23 00:00:22 2013 -0400
Commit: https://github.com/nwf/dyna/commit/2c654e96aeba466d236043197f0c127c60e047f8

What am I missing?

Counting revisions relative to a tagged version. Many people recommend "git describe" for this purpose -- it provides more user-friendly info, and as an officially supported feature of git, it is likely to work long-term and in situations with branches or uncommitted revisions. I am unable to play much with git describe since none of our revisions are tagged, but here is the sales pitch: http://gitfu.wordpress.com/2008/05/25/git-describe-great-another-way-to-refer-to-commits/

"0.4" is some number @nwf declared as Dyna's version (e.g. perl5 or Python 2.7).

Yes, and correctly so, since the last 2005 release was 0.3.10. (But I'll pretend below that 0.3 is actually our own previous tagged version in this git repo.)

If you ask dyna --version and you receive "version: 0.4..." what else could that mean?

If the version is reported as 0.4, then that ought to mean, unambiguously, that it is the official tagged 0.4 release!

Think about novice users. People may not understand the significance of the "Commit:" line, and may easily think that the version number is the important info, which means that they will mail us "I'm working with Dyna 0.4" (which is incomplete) or fail to understand why two users running 0.4 are not getting the same results.

So for something that is not an official tagged release but rather comes between 0.3 and 0.4, I would prefer to report a version number like "Dyna 0.3 rev 477" or "Dyna 0.4 pre-release 477." This also makes it easy to see that one version is later than another.

(Regarding whether we should report the version as a patchlevel on 0.3 or a pre-release of 0.4, I'm not sure how to handle that -- wouldn't we want to maintain those on separate git branches if 0.4 is internally under development but we still want to push patches to 0.3?)

If we didn't have git describe, then here are ways we'd get the elements above:

• the 0.3 comes from the last tagged version: http://stackoverflow.com/questions/1404796/how-to-get-the-latest-tag-name-in-current-branch-in-git
• the 0.4 comes from the VERSION file
• the number "477" can be obtained via git rev-list --count although this is the number of commits since the start of the repo. More generally, we should count only the revisions since the last tagged version, which can be done if we know how to refer to that version: see git help rev-list .

Also, here's one person's solution for getting the URL if we want to display that:

• http://debuggable.com/posts/git-alias-for-displaying-the-github-commit-url:49c0e1af-69e8-4b6e-89a6-066b4834cda3 (though I wonder if there's a more portable way to do this that doesn't hardcode github.com but rather looks at the local git repo info to retrieve the URL)

[timvieira]

Counting commits? really? that can't be a good way to identify a version.

On Tue, Jul 23, 2013 at 12:18 PM, Jason Eisner [email protected]:

Should look more like this:

$ ./dyna --version
Version: Dyna 0.4 pre-release 477 [or maybe Dyna 0.3.10 rev 477]
Build date: Tue Jul 23 00:00:22 2013 -0400
Commit: 2c654e9

What am I missing?

Counting revisions relative to a tagged version. Many people recommend
"git describe" for this purpose -- it provides more user-friendly info, and
as an officially supported feature of git, it is likely to work long-term
and in situations with branches or uncommitted revisions. I am unable to
play much with git describe since none of our revisions are tagged, but
here is the sales pitch:
http://gitfu.wordpress.com/2008/05/25/git-describe-great-another-way-to-refer-to-commits/

"0.4" is some number @nwf https://github.com/nwf declared as Dyna's
version (e.g. perl5 or Python 2.7).

Yes, and correctly so, since the last 2005 release was 0.3.10. (But I'll
pretend below that 0.3 is actually our own previous tagged version in this
git repo.)

If you ask dyna --version and you receive "version: 0.4..." what else
could that mean?

If the version is reported as 0.4, then that ought to mean, unambiguously,
that it is the official tagged 0.4 release!

Think about novice users. People may not understand the significance of
the "Commit:" line, and may easily think that the version number is the
important info, which means that they will mail us "I'm working with Dyna
0.4" (which is incomplete) or fail to understand why two users running 0.4
are not getting the same results.

So for something that is not an official tagged release but rather comes
between 0.3 and 0.4, I would prefer to report a version number like "Dyna
0.3 rev 477" or "Dyna 0.4 pre-release 477." This also makes it easy to see
that one version is later than another.

(Regarding whether we should report the version as a patchlevel on 0.3 or
a pre-release of 0.4, I'm not sure how to handle that -- wouldn't we want
to maintain those on separate git branches if 0.4 is internally under
development but we still want to push patches to 0.3?)

If we didn't have git describe, then here are ways we'd get the elements
above:

• the 0.3 comes from the last tagged version:
  http://stackoverflow.com/questions/1404796/how-to-get-the-latest-tag-name-in-current-branch-in-git
• the 0.4 comes from the VERSION file
• the number "477" can be obtained via git rev-list --count although
  this is the number of commits since the start of the repo. More generally,
  we should count only the revisions since the last tagged version, which can
  be done if we know how to refer to that version: see git help rev-list.

Also, here's one person's solution for getting the URL if we want to
display that:

http://debuggable.com/posts/git-alias-for-displaying-the-github-commit-url:49c0e1af-69e8-4b6e-89a6-066b4834cda3(though I wonder if there's a more portable way to do this that doesn't
hardcode github.com but rather looks at the local git repo info to
retrieve the URL)

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/62#issuecomment-21426067
.

[jeisner]

You must have missed that in the initial batch of StackOverflow links: lots of people are doing it and so is git describe itself, so it's recommended.

That's not the complete ID (which is why we also provide the SHA). But it is concise and user-friendly information that immediately shows how out-of-date someone is, as well as reminding us that after 477 commits maybe it's time for a new version number. Again, here's a sales pitch: http://gitfu.wordpress.com/2008/05/25/git-describe-great-another-way-to-refer-to-commits/

[timvieira]

I've made a few changes. We still don't have tagged releases so it doesn't like quite the way you suggest.

$ ./dyna --version
Version: Dyna 0.4 pre-release heads/master-112-gd12e1ca
Build date: Sun Jul 28 14:50:31 EDT 2013
Commit: https://github.com/nwf/dyna/commit/d12e1ca0cb6db99f1cc316287ca19805fd2f13a8

[timvieira]

There is a VERSION file which is updated whenever make build happens.

[timvieira]

Can I close this?

[jeisner]

Can we now decree that we are at released version 1.4.0, and tag the
version, and then use the version number + patchlevel (+ sha) as suggested
above?

On Fri, Aug 2, 2013 at 10:18 AM, Tim Vieira [email protected]:

Can I close this?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/62#issuecomment-22008473
.

[timvieira]

Any thoughts @nwf?

On Fri, Aug 2, 2013 at 12:38 PM, Jason Eisner [email protected]:

Can we now decree that we are at released version 1.4.0, and tag the
version, and then use the version number + patchlevel (+ sha) as suggested
above?

On Fri, Aug 2, 2013 at 10:18 AM, Tim Vieira [email protected]:

Can I close this?

—
Reply to this email directly or view it on GitHub<
https://github.com/nwf/dyna/issues/62#issuecomment-22008473>
.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/62#issuecomment-22017832
.