Fwd: Migration of (dhcp-client-service)

Fwd: Migration of (dhcp-client-service)

[swedebugia]

[-- Attachment #1: Type: text/plain, Size: 2940 bytes --]


-------- Forwarded Message --------
Subject: 	Migration of (dhcp-client-service)
Date: 	Sun, 4 Nov 2018 07:59:51 +0100
From: 	swedebugia <swedebugia@riseup.net>
To: 	Ludovic Courtès <ludo@gnu.org>



Hi

In this commit

http://git.savannah.gnu.org/cgit/guix.git/commit/?id=39d7fdce453b0ca23ecbed72048647debbaa58a6

you deprecated (dhcp-client-service) in favour of (service 
dhcp-client-service-type)

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

I would like us to be careful and document these types of changes in a 
way that paves the way for newcomers to easily understand what is going on.

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.

Cheers

Swedebugia

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

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


[-- Attachment #2: Type: text/html, Size: 17244 bytes --]

Re: Fwd: Migration of (dhcp-client-service)

[swedebugia]

[-- Attachment #1: Type: text/plain, Size: 3706 bytes --]

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

[-- Attachment #2: Type: text/html, Size: 6004 bytes --]