bug#40848: doc: chapter "Building from Git" in "Contributing" misses to list required packages

[Stefan]

Hi!

The chapter "Building form Git" starts with two git commands to clone and 
verify the code. Unfortunately it misses to mention before that two packages 
are required for this to be working: git and gnupg.

While the former is obvious, the gnupg package is not that obvious. If you 
missed to install it, then the "git verify-commit" prints some error messages 
with "error: cannot run gpg". And unfortunately gpg is not the package name to 
install to solve this error.

It would be beneficial, if the two required packages git (or git-minimal?) and 
gnupg would be mentioned before starting with commands which would fail 
otherwise.

It would further help to repeat the wget command from the installation section 
to fetch the keys necessary for this verification, as there are other numbers 
printed beside the mentioned 3CE4645…

However that wget command requires yet another package to be installed: wget.

Finally trying to verify commit f84b0363053e5479464f6ce6ded45f80360d90fc it 
leaves this unresolved key: 

gpg: Signatur vom Sa 28 Mär 2020 21:30:07 CET
gpg:                mittels RSA-Schlüssel 
39B33C8D94480D2DDCC2A4988B44A0CDC7B956F2
gpg: Signatur kann nicht geprüft werden: Kein öffentlicher Schlüssel

The next command mentioned then is "make authenticate". It fails because the 
make package first needs to be installed. But even if this is done, it fails 
with "make: *** Keine Regel, um „authenticate“ zu erstellen.  Schluss." There 
has yet no Makefile been created.

Further down the commands "./bootstrap" and ".configure" are mentioned, which 
are both required to create the needed Makefile. But to be able to run this, 
all the listed dependencies need to be installed. 

Only after struggling down to the failing "make authenticate" there is the 
finally helpful command "guix environment guix —pure".

So to sum it all up: the packages to install and missed to mention are

 • git (or git-minimal?)
 • gnupg
 • wget 

The wget command to download the key should ideally be repeated. The "make 
authenticate" command is not helpful at all to be mentioned that early.

It would instead be very helpful, if first "guix environment guix —pure" would 
be mentioned, and if this (or a similar command) would also provide git, gnupg 
and wget to be able to fetch and verify the source code of guix as described by 
the first two commands "git clone …" and "git verify-commit …".

The "make authenticate" command must not be mentioned before but only after the 
"./bootstrap" and "./configure" commands.  Both "./bootstrap" and "./configure" 
should ideally be boxed like the other commands. This boxing would also help 
the important argument "--localstatedir=/var" to not be overseen.

In my case after all this and running ".configure" successfully, "make 
authenticate" still failed, because I relied on "guix environment guix —pure" 
to have a dependency to gnupg to have the gpg command accessible, which is 
unfortunately not the case.

I then exited the environment and started a new one with "guix environment guix 
--pure --ad-hoc gnupg" and ran "make authenticate" now with this result:

stefan@guix ~/development/guix [env]$ make authenticate
Authenticating Git checkout...
Authenticating d68de95 to f84b036 (14629 commits)...
[###                                                                           
]Backtrace:
          12 (apply-smob/1 #<catch-closure 3e6b3140>)
In ice-9/boot-9.scm:
    705:2 11 (call-with-prompt _ _ #<procedure default-prompt-handle?>)
In ice-9/eval.scm:
    619:8 10 (_ #(#(#<directory (guile-user) 3e77d140>)))
   293:34  9 (_ #(#(#(#(#(#(#(#(#(#(#<?> ?) ?) ?) ?) ?) ?) ?) ?) ?) ?))
In ice-9/boot-9.scm:
    142:2  8 (dynamic-wind _ _ #<procedure stop ()>)
    152:2  7 (with-fluid* _ _ _)
In srfi/srfi-1.scm:
   466:18  6 (fold #<procedure 45b346c0 at ice-9/eval.scm:336:13 (a?> ?)
In ice-9/eval.scm:
   293:34  5 (_ #(#(#<directory (guile-user) 3e77d140> #<proce?> ?) ?))
    619:8  4 (_ #(#(#(#<directory (guile-user) 3e77d140>) #<gi?> ?) ?))
   626:19  3 (_ #(#(#(#<directory (guile-user) 3e77d140>) #<gi?> ?) ?))
In ice-9/boot-9.scm:
    152:2  2 (with-fluid* _ _ _)
    142:2  1 (dynamic-wind #<procedure 45cb9240 at ice-9/eval.scm:3?> ?)
    142:2  0 (dynamic-wind #<procedure 45cb9100 at ice-9/eval.scm:3?> ?)

ice-9/boot-9.scm:142:2: In procedure dynamic-wind:
Throw to key `srfi-34' with args `(#<condition &message [message: "could not 
authenticate commit 77704cb13e5bebf412297dab764a00849a3cfdc0: key 
A0C5E3522EF8EF5C64CDB7F0FD73CAC719D32566 is missing"] 45cbb800>)'.
make: *** [Makefile:5895: authenticate] Error 1

The documentation then finally suggest to run "make check". Isn't the actual 
build step with "make" missing?


I'm currently using 

guix describe
Generation 5    28. März 2020 18:44:49  (aktuell)
  guix e425713
    Repository-URL: https://git.savannah.gnu.org/git/guix.git
    Branch: master
    Commit: e4257138fe1d924c56c9979b75319585b9251fb7

My profile is empty, no installed packages – I removed all packages again after 
obtaining the source code and before running "guix environment guix --pure 
--ad-hoc gnupg".


Bye

Stefan