'pre-inst-env guix --version' is not updated by new commits"

When I clone and build Guix from scratch, it produces the untracked file

"doc/stamp-1" which contains the version number built into the Guix doc

and appears to be created from a call to 'git describe'.

But with subsequent git commit/make cycles the version does not

change. It doesn't change when the guix package is updated either. For

example, after pulling and building the recent commit updating the guix

package ...

commit 8b3aea9d9e022b20137cec93f668df8fa051abd9

Author: Ludovic Courtès <ludo@gnu.org>

gnu: guix: Update to 77a1aac.

* gnu/packages/package-management.scm (guix): Update to 77a1aac.

g1@sysi31 ~/gom/.emacs.d/guix/guix [gmm]$ git describe 8b3aea9d9e022b20137cec93f668df8fa051abd9

v0.14.0-6300-g8b3aea9d9

"doc/stamp-1" and guix version remain "stuck" on June 8th ...

g1@sysi31 ~/gom/.emacs.d/guix/guix [gmm]$ cat doc/stamp-1

@set UPDATED 8 June 2018

@set UPDATED-MONTH June 2018

@set EDITION 0.14.0.5478-1458f7

@set VERSION 0.14.0.5478-1458f7

g1@sysi31 ~/gom/.emacs.d/guix/guix [gmm]$ ./pre-inst-env guix --version

guix (GNU Guix) 0.14.0.5478-1458f7

They remain stuck after 'make clean; make', and './bootstrap;

./configure; make' The only way I found to "unstick" them is 'sudo git

clean -dfx'.

Side questions:

1) why don't you gitignore "doc/stamp-1"?

2) why don't you gitignore .po files?

TIA - George

Hello George,

George Clemmer <myglc2@gmail.com> skribis:

Currently the version number is hardcoded in ‘configure.ac’, so the fact

that running “git pull && make” doesn’t change it is expected. So to

me, it’s not a bug.

We could improve on that (see for instance how Guile does it with

build-aux/git-version-gen), but it still won’t be updated at each commit

because that’d be inconvenient: ‘config.h’ would regenerated, so in turn

we’d need to rebuild all of the C++ code.

‘guix pull’ does the right thing though, which I think is more important

than the build tree.

Good idea, done! :-)

Because they are checked in.

Thanks for your report.

Ludo’.

Ludovic Courtès <ludo@gnu.org> writes:

Hi Ludo’,

Ok, cool. Thanks for the clarification. So... how about adding a

footnote to '(guix) Running Guix Before It Is Installed' something like

...

(3) The Guix version in the Guix build is set by './configure'. Thus,

when guix is run from the Git working tree by './pre-inst-env guix' or a

'~/.config/guix/latest’ symlink, the version reported by 'guix

--version' is not updated by subsequent 'git pull; make' steps. To

update the version (and rebuild everything), you may use 'git clean

-dfx; ./bootstrap; ./configure; make'.

Note: I also tried 'make distclean' and 'make maintainer-clean' which

didn't work.

Agreed.

Thanks!

I guess I meant to say, why does the build change these checked-in

files? It seems like they should be ignored.

TIA - George

George Clemmer <myglc2@gmail.com> skribis:

I’m not comfortable documenting this because it’s nothing specific to

Guix.

Besides, note that ~/.config/guix/latest no longer exists.

The build changes them only if you start anew. In normal circumstances

(meaning you didn’t run “distclean”), they remained unchanged if I’m not

mistaken.

So yeah, it’s occasionally annoying, but I’m not sure how to fix this.

Ludo’.

Ludovic Courtès <ludo@gnu.org> writes:

So to summarize: This behavior is a side effect of how GNU tools

work. It is obvious to anyone who understands them. You don't want to

describe things that are obvious. I understand.

But I think many users don't have a clue about GNU build tools. They may

be puzzled by how pre-inst-env works. I think the footnote would be

helpful for them. I urge you to reconsider.

Yes, I saw you revamped Guix pull but I haven't actually used guix pull

in over a year. I need to check the new one out.

- George

Hello,

George Clemmer <myglc2@gmail.com> skribis:

It’s not that I find it “obvious” etc. This specific part of the manual

targets an audience of developers, and I think it’s reasonable to expect

this audience to know where to look things up.

The other aspect, from a maintenance and readability viewpoint, is that

we could quickly add up lots of explanations that we’ll have to keep

up-to-date and that may make more important information harder to find.

I hope that makes sense, but I’m happy to hear what others think.

Ludo’.

On Wed, Jun 13, 2018 at 08:54:49AM +0200, Ludovic Courtès wrote:

Yeah, I'm worried about this too. It's tough to strike the correct

balance.

Leo Famulari <leo@famulari.name> writes:

IMO Guix is great for hackers, maintainers and sysops. The doc is

appropriate for such users, well done, spare, and already voluminous.

This footnote suggestion, and others rejected in the past, are motivated

by my assumption that you will want to make Guix attractive to less

sophisticated users.

Maybe my assumption is wrong? Maybe you want only "elite" users?

Or maybe you want to defer the less sophisticated users to later in the

development cycle?

Hi George,

George Clemmer <myglc2@gmail.com> writes:

But non-hacker users can use Guix pull! Running Guix before it is

installed (with pre-inst-env) is described in the manual as a "Hacker

trick".

Guix pull is well documented, and should be usable for non-elite users.

Clément

Hi George,

George Clemmer <myglc2@gmail.com> skribis:

No, definitely not; I’m sorry if this is the impression this gave.

Like I wrote, my main concern is about keeping the documentation focused

and maintainable. Sometimes we have to document things that are

technically outside of Guix because there’s no real canonical

documentation and because users would be impaired without it—I’m

thinking for instance of bits in the “Preparing for Installation”

section.

In this case, we’d be documenting something that’s both outside of Guix

and not vital for routine usage, and that’s mostly covered by the

Autoconf manual. Hence my reluctance.

I hope that makes sense.

Ludo’.

Clément Lassieur <clement@lassieur.org> writes:

Sorry if I sounded a bit rude, it wasn't my intention. :-)

Ludovic Courtès <ludo@gnu.org> writes:

Hi Ludo’,

I see the situation this way:

The current doc reflects the needs and sensibilities of the hackers,

maintainers, and sysops that have built Guix. These "elite" users have

different needs and judge what is important quite differently from end

users. This guarantees that the current doc is inadequate for end users.

So, if, as you say, you want to make Guix accessible to end users, you

need to make changes in the doc. The questions: How? What?

May I suggest ...

a) Adopt a less defensive posture when responding to user questions,

comments, and bug reports.

b) Be pro-active about capturing support resolutions in the doc.

This thread presents a nice example of what I am talking about. To

recap:

I said: I use 'pre-inst-env guix' this way and this is a bug.

You said: Developers expect this, so it's not a bug.

A less defensive response: Hmm, You are using 'pre-inst-env guix' in a

way we didn't anticipate. What are the benefits of using it this way? I

see how this is a bug for your use case.

We discussed a workaround. I suggested adding it to the doc.

You said: I’m not comfortable documenting this because it’s nothing

specific to Guix.

I said: I urge you to reconsider.

You said: This part of the manual targets developers... they know where

to look things up. [The more we write the more we have to maintain.]

And Clément Lassieur <clement@lassieur.org> added:

OK, but I'm non-elite and I have used Guix for 2+ years. I have tried

both. I prefer pre-inst-env. I expect others will too. The fact is that

pre-inst-env does not correctly report the version after 'git pull;

make'. How can you know that this won't be a problem for other users?

It only takes 4 lines to explain this and provide a workaround, e.g.,

Proposed (revised) footnote:

(3) The Guix version in the Guix build is set by './bootstrap'. Thus,

the version reported by './pre-inst-env guix --version' is not updated

by subsequent 'git pull; make' steps. To update the version (and rebuild

everything), use 'git clean -dfx; ./bootstrap; ./configure; make'.

- George

Hi George,

[…]

“pre-inst-env” really should not be used by people other than

developers. It is only available when building Guix from a clone of the

git repository.

We do not recommend “pre-inst-env” for any other purpose than to make

changes to the code, so I would not like to document the quirks and

limitations of “pre-inst-env” in the manual, as this is not how Guix is

supposed to be used generally.

I’m wary of adding this for similar reasons that Ludo wrote earlier. In

my opinion this ends up cluttering the manual with notes and what I

consider to be only tangentially relevant for readers of the manual.

--

Ricardo

Ricardo Wurmus <rekado@elephly.net> writes:

Hi Ricardo,

Please read further down the original post. I think you will find that I

already addressed your points.

Collectively, the responses here bring to mind a Harvard Business School

case study I was taught in 1983. The gist of it: Bakers at Holsum Bread

told a salesman that they had figured out how to run his company's bread

making machine at twice the design speed. Because this was twice as fast

as the competitor's machine, they wanted to place a big order for more

machines. When the salesman told the company engineer about the order he

said, "You can't sell any more machines to Holsum because they aren't

using my machine properly!"

- George

Hi Nils,

Nils Gillmann <ng0@n0.is> writes:

[...]

[...]

[...]

I think the Guix strategy, AIUI, of putting 99.9% of the doc effort into

a single doc via Texinfo is very efficient. INFO and HTML reach the two

extreme user types: hackers that use INFO and people use that google.

Partitioning the problem into sub-parts is tempting. But it increases

the risk of a sub-part drifting out of date at which point it is better

to not have had the sub-part ;-)

The Guix "mico-man-page" effectively eliminates a sub-part. Hackers can

use INFO and people who google don't use man, so I think the micro-man

approach is fine.

I think the most promising and productive way for Guix to improve the

end-user-friendliness of the doc is to use end-user "support incidents"

to drive doc additions. At the end of an incident the user question is

fresh in your mind, you have information that you know could have been

helpful to at least one user, and you capture the support effort into

something longer lasting.

- George

Ricardo Wurmus <rekado@elephly.net> writes:

An alternative might be to change the output of “guix --version” in the

presence of GUIX_UNINSTALLED, which is set by “pre-inst-env”. This

could be a simple change in “show-version-and-exit” that would use

something other than “%guix-version” when GUIX_UNINSTALLED is set.

What do others think?

--

Ricardo

On 06/16/2018 at 00:24 Ricardo Wurmus writes:

I like it.