Hello Matt; sorry, I've been distracted and almost missed your reply a few weeks ago.
Matt <m...@excalamus.com> writes:
[...] I tried to write a tutorial on packaging GNU Hello. Really, if I were to look over the shoulder of someone packaging GNU Hello, what would it look like? Why are they doing what they're doing in addition to what and how. It's not obvious at all. The Cookbook touches on GNU Hello. However, it's hard to see how someone new to the details of Guix packaging, such as myself, is supposed to go from 'Section 2.1.1 A “Hello World” package' to actually packaging something in the wild. All paths inevitably lead to the Guile manual.
Yes, there are several layers of complexity at play: building the target package (not easy when all dependencies must also be packaged), and specifying the package in Guile.
I'm not that uncomfortable with scheme, though I don't think I fully understand g-expressions yet. It would be easier if I could get Geiser working for looking up symbols, but if the docs were better I suppose I wouldn't have to read the code.
I have successfully packaged some of my own things, trying to use guix for managing dev environments; it's not too bad for some things, but gets much more complicated when I have to step outside the comfort zone of directly using existing packages and build systems as inputs. The other major thing I'm not yet familiar with is the patch submission and management process; not that I have anything patch-worthy yet, but it is a hurdle.
Packaging is inherently complex. It requires *at least* knowing something about Unix-like systems, build systems, and details of software development ranging from general programming concepts to specific applications to all the surrounding tooling.
I think it would be fair to assume minimal competence with using a shell. Everything else should be given as clear, exact steps to take ('mkdir package' not 'make a directory for your package'), so that even someone who knows nothing can perform the steps and produce the result.
A common assumption is that "they don't have to know anything before getting started". Unfortunately, this is not true. Fortunately, we can often abstract this away by giving only the necessary information (not easy to do!) for whatever we're explaining and handing off details to another resource. This is where the Guile documentation fails Guix.
I think of tutorials as exposure rather than explanation, so the tutorial itself shouldn't need to explain much or rely on external resources. However, once the reader has finished the tutorial, they should be able to look up the steps they were exposed to. That is what the rest of the documentation is for, so I agree it should be improved. It's less clear how to "fix the documentation" than "write a tutorial" though. Maybe we can start with the tutorial, then improve the documentation for everything it used?
I'd be happy to work alongside you.
Cool! I'm going to be pretty distracted this week, but we could start working on it asynchronously. Any thoughts on process? Maybe we could have a repo managed the same way Guix is, so I can learn that at the same time. (That is, emails for discussion and patches to the tutorial) How hard would that be to get or set up? That could also be the 'practice repo' people doing the tutorial would use for the final submission parts.
After that, I think the first step is picking an easy but non-trivial package to do. Maybe it should be one that's already been packaged... I went through a list of packages that I wished Guix had, and sadly none of them were easy enough for me to do. My first choice was INN (a Usenet server), but it has multiple service dependencies I wasn't sure how to handle. My other choices were apparently in Rust, which always has waaay too many deps. We could also do a better Hello tutorial. Thoughts?
Thanks, -Samuel
