Subject: [bug#52600] [PATCH] doc: Document (gnu services configuration).

From: Xinglu Chen <[email-masked]>
Date: Thu, 23 Dec 2021 11:42:18 +0100

Hi,

Ludovic schrieb am Mittwoch der 22. Dezember 2021 um 23:14 +01:

> Hi,
>
> Xinglu Chen <[email-masked]> skribis:
>
>> * guix.texi (Complex Configurations): New node.
>
> Great work!  I applied it and fixed typos Attila reported plus “bindgs”
> (instead of “bindings”).

Great, thanks for taking a look.  I didn’t receive any message from
Attila though, and there doesn’t seem to be anything on the ML either.
I guess he sent it when all the GNU infra was down, but unless he didn’t
Cc me, I don’t see why I wouldn’t receive it.

>> This patch documents the complex beast that is the (gnu services
>> configuration) module.  I only documented the things that existed before
>> the Guix Home merge, though.  There were a lot of things to document, and
>> I hope that my explanations aren’t too confusing (It took me a while to
>> wrap my head around all of this).  :-)
>
> It looks very clear to me.

Good to know.  :-)

>> What is still missing is some kind of style guide for writing Guix
>> services:  When should one use (gnu services configuration) vs plain
>> (guix records)?  Should we try to create bindings for all config options
>> or should we provide an “escape hatch” for users?
>>
>> I would personally prefer if most (if not all) services were written
>> using (gnu services configuration), but I don’t really think refactoring
>> existing services would really be worth it.  But that’s another discussion.
>
> Yeah.  So far the (unwritten) guideline has always been:
>
>   • Have record types that provide bindings for all or most of the
>     available options;
>
>   • Always provide an “escape hatch” so users can insert raw
>     configuration snippets, either because the bindings don’t cover
>     everything, or because they have an existing config file they’d like
>     to reuse.
>
> We should probably write it down somewhere.  Maybe we need a new section
> next to “Packaging Guidelines” to discuss system services?

That sounds like a good idea; Andrew started to work on something like
that[1].

> As for ‘define-configuration’ vs. (guix records) vs. SRFI-9…  I don’t
> think we really discussed the issue or agreed on something.
>
> For the rather simple services I wrote, I was happy to use plain records
> and home-made serializers rather than ‘define-configuration’.  But
> overall it seems to make more sense to recommend ‘define-configuration’
> unconditionally.  I guess it already has serializers for the most common
> formats, which are all alike, so we should be able to avoid
> boilerplate.
>
> Thoughts?

Agreed, since ‘define-configuration’ & friends are now documented, it
makes even more sense to use them.

> Thanks for substantially improving the manual!

You are welcome!  :-)

[1]: <https://yhetil.org/guix/[email-masked]/>