Inaccurate stable version designation when not building in a git clone

[ryandesign]

Based on this output you'd think I was running the stable 1.70 version of stklos:

% stklos
  \    STklos version 1.70  (Id: stable-1.70)
   \   Copyright (C) 1999-2023 Erick Gallesio <eg@stklos.net>
  / \  [Darwin-21.4.0-x86_64/pthreads/libedit/utf8]
 /   \ Type ',h' for help
stklos> ^D
% 

but I'm not. I'm running nearly the latest code from the git master. It's just that I didn't build this from within a git clone; I build it from a tarball.

From the main page of this repository, click the green Code button, then click Download ZIP to get an archive of the latest code on master. (You can construct URLs to download archives of any commit or tag.) Extracting this archive and building it, stklos will identify itself as stable even though it's some random development version.

If you want to distinguish stable and unstable versions in your UI, then there has to be some place in your source code that states whether the code is stable or unstable. You can't rely on external factors like the output of the git program.

[jpellegrini]

Hi @ryandesign !
Actually, each build of STklos contains the relevant information. It's just not being shown in the banner:

$ stklos
  \    STklos version 1.70  (Id: 590c7270)
   \   Copyright (C) 1999-2023 Erick Gallesio <eg@stklos.net>
  / \  [Linux-6.1.0-5-amd64-x86_64/pthreads/readline/utf8]
 /   \ Type ',h' for help
stklos> (%stklos-git)
(#:branch "master" #:commit "590c7270" #:tag "stklos-1.70" #:modified ("doc/Makefile.in" "src/Makefile.in"))

In Scheme, it is the %stklos-git procedure; in C, it is the STk_stklos_git function...

@egallesio - what about changing it in the banner?

[jpellegrini]

About %stklos-git and other procedures...
Do you have readline? If you do, you can start stklos, type a letter, (or %) then hit tab... Readline will suggest completions.

[ryandesign]

This is the line of the output I was objecting to:

\    STklos version 1.70  (Id: stable-1.70)

[jpellegrini]

This is the line of the output I was objecting to:

Yes. We can easily change the banner. But releases are just tags from git, so we'd need a way to tell that we're building that specific commit (tagged 1.80 for example) and use it in the banner.

[jpellegrini]

I think I can come up with a solution to this.

[ryandesign]

From my perspective it would suffice for the banner to say "Id: unknown" if a development build happens outside of a git clone. The only real bug that needs to be fixed is proclaiming a non-stable version to be stable.

I'm working on updating stklos in MacPorts and since there have been so many changes since 1.70 I'm also working on offering an stklos-devel port to track git master more closely. It was in the process of doing this that I noticed the problem. I'm working around it by patching utils/generate-git-info; I know what git commit I fetched a tarball of, so I can patch it into that script.

If you wanted to be extra helpful you could make the git commit a Makefile variable that I could override when building, such as:

make COMMIT=abcdef01

[jpellegrini]

I'm almost finishing a solution :)

[jpellegrini]

See PR #516 -- maybe it can be enhanced...

[jpellegrini]

Hm. but that solution will not work if you're out of a git checkout.

[ryandesign]

Right:

% stklos
  \    STklos version post-1.70 (git commit stable-1.70)
   \   Copyright (C) 1999-2023 Erick Gallesio <eg@stklos.net>
  / \  [Darwin-21.4.0-x86_64/pthreads/libedit/utf8]
 /   \ Type ',h' for help
stklos> 

[jpellegrini]

Fixed, perhaps?

[ryandesign]

Now, when in a git clone, I have:

% stklos 
  \    STklos version post-1.70 (git commit 590c7270)
   \   Copyright (C) 1999-2023 Erick Gallesio <eg@stklos.net>
  / \  [Darwin-21.4.0-x86_64/pthreads/libedit/utf8]
 /   \ Type ',h' for help
stklos> ^D

and when not in a git clone, I have:

% stklos
  \    STklos version 1.70
   \   Copyright (C) 1999-2023 Erick Gallesio <eg@stklos.net>
  / \  [Darwin-21.4.0-x86_64/pthreads/libedit/utf8]
 /   \ Type ',h' for help
stklos> ^D

[jpellegrini]

Ok - if you're outside git, we assume it's a stable tarball... I guess you mean you want to compile arbitrary tarballs, from any commits right?
I'm not sure how to differentiate a stable tarball from a tarball from some commit...

[lassik]

IMHO no build should ever say that it's an official version unless a build flag is explicitly given to say so. All builds (both with and without git) should be "unofficial" or "unstable" by default.

There are just too many things that can go wrong in trying to make an official build.

A package manager like MacPorts can put the "stable" flag in its build recipe (ideally with a suffix that says that build of STklos is from MacPorts).

[lassik]

Concretely, something like this (but better):

make OFFICIAL=MacPorts

    STklos version 1.70 (MacPorts)

make  # from source tarball without git

    STklos version 1.70 (unofficial)

make  # in git repo

    STklos version 1.70-590c7270

[jpellegrini]

@lassik what about the releases on github? Aren't they just the code checkout for specific tags made into tarballs?

[lassik]

Yes, they are.

IMHO even if one downloads a release tarball and builds it, it should still say "unofficial" or "self-built" or something like that. Building software has many complications. The default assumption should be that the user didn't get everything right.

These versions would accurtely describe the actual situations that users are likely to have:

STklos version 1.70 (self-built)
STklos version 1.70 (MacPorts)
STklos version 1.70 (Mac Homebrew)
STklos version 1.70 (FreeBSD ports)
STklos version 1.70 (Debian Linux APT package)

and add the git information as needed.

[lassik]

If a bug report says "self-built" that leads naturally to questions such as "did you change any files", "what configure flags did you use", etc.

[jpellegrini]

"did you change any files", "what configure flags did you use"

But those things can also happen with an official release (it's source, not binary...)

I'd wait for @egallesio to say what he prefers as a solution to this...

[lassik]

If the user would have to type make official instead of the usual make then it is unlikely to happen. (Could use an even less ambiguous word than "official" :-)

[ryandesign]

I'm not sure how to differentiate a stable tarball from a tarball from some commit...

See #515 (comment): "If you want to distinguish stable and unstable versions in your UI, then there has to be some place in your source code that states whether the code is stable or unstable. You can't rely on external factors like the output of the git program."

[jpellegrini]

If you want to distinguish stable and unstable versions in your UI, then there has to be some place in your source code that states whether the code is stable or unstable

Well, that is sort of what happens - the build system writes a header file that later is incorporated into STklos. The problem is that the header needs to reflect the context (stable tree or not).

[ryandesign]

that is sort of what happens

No, there is no place in the code in the git repository that says "this code is stable" or "this code is unstable/developent". There is a script that attempts to infer that information by invoking the git program; not the same thing.

What I am proposing is that the release process be amended, so that in addition to updating the changelog and updating the version number throughout, a flag (something in the configure script, or a macro in a header) would be switched from "this is unstable/development" to "this is stable". Then a tag is made of that commit. Then the flag is switched back to "this is unstable/development" in the next commit.

[ryandesign]

I'm not saying you have to distinguish stable and unstable versions. You don't. The current code seems to want to, but does it wrong. So either don't attempt to distinguish them and just print whatever version number is in the source, or if you want to distinguish them, then make sure it's accurate.

[lassik]

From experience, it won't be accurate unless it's unstable by default.

make should take a string whose default value is self-built. MacPorts can pass the string MacPorts, etc.

[jpellegrini]

@ryandesign ok, no problem. I'm not the one who decides that anyway. :) I just thought I could help if it would be acceptable to have git tags as an indication of a stable release - but again, it's not my decision, and I have no problem with any solution that comes up for this.

[egallesio]

Now, stable version are explicitly tagged as “stable”. That means that when a stable release is built, the configure.ac is set to “stable” and flipped to unstable just after. The banner also indicates the stability status of a version.
The version number is also an indication: "2.00" is a stable version and "2.00.123" is an unstable version, which is 123 commits after the "2.00" release. It should solve this issue.