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

["Ludovic Courtès" <ludo@gnu.org>]

Hi,

Xinglu Chen <public@yoctocell.xyz> skribis:

> * guix.texi (Complex Configurations): New node.

Great work!  I applied it and fixed typos Attila reported plus “bindgs”
(instead of “bindings”).

> 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.

> 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?

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?

Thanks for substantially improving the manual!

Ludo’.