Best practices for writing services

[Xinglu Chen <public@yoctocell.xyz>]

Hi Guix,

I am going to write an mcron service for `guix home`[1][2] and before
proceding, I would like to get some suggestions on what the best
practices are for writing services in Guix.

Currently there seems to be two main ways to do this, the first one
is the define one or more records for the configuration field of a
service using `define-record-type*`, see the tor service in (gnu
services networking) for example.  The other method is to use
`define-configuration` to declare the configuration fields of a service,
see the transmission service in (gnu services file-sharing) for example.

The first method seems to be the more common one but the developer
usually has to write a lot of things manually.  The "real" configuration
file for the program or is usually created by concatenating a bunch of
strings and the developer has to write documentation for all the
configuration fields manually.

The second method removes quite a lot of boilerplate and the developer
will define different serializers that convert scheme syntax like lists,
alist, boolean... to the "real" configuration syntax of the program.  It
also does some automatic typechecking to some degree and allows the
developer to write docstrings for each configuration field.  There is
then a procedure called `generate-documentation` which can automatically
generate texinfo documenation from the docstrings.

I couldn't find any information in the manual regarding what conventions
should be used when writing services for Guix and would like to hear
from more experienced Guix hackers what the best practices are.

[1]: https://yhetil.org/guix-devel/878s6u2pco.fsf@trop.in
[2]: https://lists.sr.ht/~abcdw/rde-devel/%3C87h7l9r9xm.fsf%40yoctocell.xyz%3E