Re: [gentoo-dev] Re: repo/gentoo.git, or how committing is challenging

[Patrick Lauer <patrick@gentoo.org>]

On 12/21/2015 04:21 AM, Ryan Hill wrote:
> On Sun, 13 Dec 2015 19:00:45 -0800
> Brian Dolbec <dolsen@gentoo.org> wrote:
>
>
>> But, one of the biggest things keeping me from doing more work on it
>> when I do have some time, is the fact that barely any of the devs seem
>> to care (other than the OP, who just seems to bitch about everything
>> not working for him).  Since the GLEP 63 spec has been approved.
>> Barely any of the gentoo developers have even tried to update their gpg
>> key or generate a new one that does meet the spec.  For that reason, I
>> have not endeavored to get more done in it.  I've been trying to
>> keep the gentoo-devs seed file reasonably up to date, but since there
>> are few devs actually fixing or generating new keys, it is not needed
>> that often.  In fact weeks go by before there is a change in LDAP in
>> regards to gpg keys.
>>
>> As Andrew pointed out in another reply, there is a fairly decent
>> document about generating new gpg keys either directly using gpg or
>> using gkeys-gen (gkeys-gen-9999) has the most troublesome bugs fixed in
>> it btw).
> It's a little difficult for people to generate new keys with gkeys-gen when
> the version of gkeys-gen in the tree is completely and utterly broken, and has
> been for almost a year now.
Wiki says:

"In this guide we are going to show you how to create a GLEP 63
<https://wiki.gentoo.org/wiki/GLEP:63> based OpenPGP Key using
app-crypt/gkeys-gen
<https://packages.gentoo.org/packages/app-crypt/gkeys-gen> tool which is
the official way of managing OpenPGP keys in the Gentoo Infrastructure."

So either the documentation is wrong, or we're supposed to use a broken
tool.

Interesting challenge!
>  The last time I tried to make a new key it spit
> out a bunch of errors and tried to put data in $HOME/~/gkeys-user/gpghome.
> Like it didn't expand the tilde, but made a directory literally named '~'.  I'm
> supposed to use this for security sensitive data?  You want me to use a
> potentially unstable live ebuild instead?  Well, no, that's not gonna happen.
It gets even better when you try to read the code. But, not to worry -
it's actually pretty easy. Took me only about 4h to combine the
fragments together ...


So, first part of the puzzle:
https://wiki.gentoo.org/wiki/GLEP:63

Build a gpg.conf with the suggestions there.

Now read http://www.gnupg.org/gph/en/manual.html ... well, the
interesting part is:

"""
$ gpg --full-gen-key

Your selection? 4
What keysize do you want? (2048) 4096
Key is valid for? (0) 36m
"""
Those are the required base parameters, all other questions are
identifier (name/email). It'll take a minute or five to collect enough
entropy.

Now you want to generate a subkey (where ${keyid} is the keyid of the
main key):

"""
$ gpg --edit-key ${keyid}
gpg> addkey
Your selection? 4
What keysize do you want? (2048) 4096
Key is valid for? (0) 12m
"""
and maybe a revocation certificate:
"""
$ gpg --output revoke.asc --gen-revoke ${keyid}
"""

What I did then was to export the subkey, and keep the main key
somewhere safe. Then import the subkey on the victim machine(s) used for
gentoo committery.

Now you need to read the gpg docs again and figure out that you need
"gpg --send-keys" to upload the key to the public keyservers.

Then you wait a few minutes for it to become visible, you can check that
on http://pool.sks-keyservers.net.

Now your wiki skills are needed, if you don't know the magic invocation
you won't find it.
Hint: https://wiki.gentoo.org/wiki/Project:Infrastructure/LDAP_Guide
||

The magic line|||||||is: "perl_ldap -b user -C gentooGPGfingerprint
"<newfp>" $USER".

So now log in to dev.gentoo.org and add your key's fingerprint there.
Wait 15 minutes.

Use that time to read https://wiki.gentoo.org/wiki/Gentoo_git_workflow

especially the repository settings chapter.


... and now you can clone the repo, and do (signed) commits. Easy!



So, our onboarding experience sucks, this information is spread out in a
way that makes it hard to find even if you know what you want.

It took me literally hours, which means every new dev trying to do this
will spend hours. It's a colossal waste of time, drains motivation, and
especially the conflicting/wrong docs are not really a good idea.

The complaints are mostly that no one seems to have thought about how a
new user will find things, so there's no combined doc. The wiki is hard
to search, making it extra challenging to figure out what to do.



How to improve? Take my email, cut out the parts that state the obvious,
turn it into a wiki page referencing the other wiki pages (if wiki is
your thing - I refuse to touch MediaWiki outside of paid work, because I
got paid too long to work with it and understand the deeply ingrained
confusion its authors had about the universe)

Or just point people at a random email, because that's about as good as
documentation.
I've wasted enough time documenting the missing pieces, instead of
running gkeys-gen and doing this whole process in under half an hour it
took me most of an afternoon, with my mood definitely not improving.


Please, stop wasting people's time, if you write code or documentation
write it once properly, don't release untested things and claim they are
an official tool, and don't ignore complaints (because they mean, as a
first approximation, that you screwed up and need to fix stuff)

Sigh.


|||