-------- Forwarded Message --------
Subject: 	Re: Migration of (dhcp-client-service)
Date: 	Sun, 04 Nov 2018 23:09:25 +0100
From: 	Ludovic Courtès <ludo@gnu.org>
To: 	swedebugia <swedebugia@riseup.net>



Hello!

swedebugia <swedebugia@riseup.net> skribis:

> I have 2 questions:
>
> 1. What is the rationale behind this? (unification? are all services
>     that end in -service going to be migrated to -service-type?)

The rationale is unification towards the ‘service-type’ style. It’s
been on-going for a couple of years now.

> 2. Is this going to affect users?
>      1. E.g. what happens if a user in 0.16 uses this in their config.scm?
>      2. Are they warned that this is deprecated since 0.16?

Currently there’s no deprecation warning (but note that
‘dhcp-client-service’ is still around.)

I’ve been meaning to add a mechanism to emit deprecation warnings in
such cases…

> In this commit you updated the documentation with this:
>
> diff --git a/doc/guix.texi b/doc/guix.texi index fde7892..f4f1994
> 100644 --- a/doc/guix.texi
> <http://git.savannah.gnu.org/cgit/guix.git/tree/doc/guix.texi?id=03fd37b4eb9ec7600c9292361177ca5a47814cf7>
> +++ b/doc/guix.texi
> <http://git.savannah.gnu.org/cgit/guix.git/tree/doc/guix.texi?id=39d7fdce453b0ca23ecbed72048647debbaa58a6>
> @@ -11546,10 +11546,11 @@ The @code{(gnu services networking)} module
> provides services to configure
> the network interface.
> @cindex DHCP, networking service
> -@deffn {Scheme Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
> -Return a service that runs @var{dhcp}, a Dynamic Host Configuration
> -Protocol (DHCP) client, on all the non-loopback network interfaces.
> -@end deffn
> +@defvr {Scheme Variable} dhcp-client-service-type
> +This is the type of services that run @var{dhcp}, a Dynamic Host
> Configuration
> +Protocol (DHCP) client, on all the non-loopback network
> interfaces. Its value
> +is the DHCP client package to use, @code{isc-dhcp} by default.
> +@end defvr
> @deffn {Scheme Procedure} dhcpd-service-type
> This type defines a service that runs a DHCP daemon. To create a
> @@ -17168,7 +17169,7 @@ A helper function to quickly add php to an
> @code{nginx-server-configuration}.
> A simple services setup for nginx with php can look like this:
> @example
> -(services (cons* (dhcp-client-service)
> +(services (cons* (service dhcp-client-service-type)
> (service php-fpm-service-type)
> (service nginx-service-type
> (nginx-server-configuration
>
> Maybe we should have a list of deprecated features with version
> numbers to help users find the information about the change if they
> experience a hiccup.

Maybe, at least post 1.0.

So far we’ve usually just updated the doc to reflect the latest API,
even when we kept deprecated APIs around. Not sure if that’s enough;
your suggestion makes a lot of sense.

> PS: I send this in private because it could perhaps be viewed as
> criticism, tho I have no such intention.

I think constructive criticism of this sort is very much welcome! It’s
what allows us together to improve the code and documentation.

Also it’s possible that others had similar questions, so it’s probably
worth discussing.

(In that spirit, feel free so send your questions to the list and/or
resend my reply.)

> PPS: I noticed this change when I downloaded bare-bones.tmpl on a guix
> 0.15 VM image and tried reconfiguring and got an error about
> dhcp-client-service-type being unbound...

Oh I see. Doc/API mismatches can be problematic indeed, and an argument
in favor of keeping documentation of deprecated interfaces.

Thanks,
Ludo’.