From mboxrd@z Thu Jan 1 00:00:00 1970 From: swedebugia Subject: Re: Fwd: Migration of (dhcp-client-service) Date: Sun, 4 Nov 2018 23:17:54 +0100 Message-ID: <0c7507d8-6f14-1442-a2f5-7aa43e4fe8b7@riseup.net> References: <871s80pka2.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="------------41EB87F335C10935C21DBE75" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:35862) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gJQkQ-0007qJ-MO for guix-devel@gnu.org; Sun, 04 Nov 2018 17:20:01 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gJQib-000052-Bb for guix-devel@gnu.org; Sun, 04 Nov 2018 17:18:08 -0500 Received: from mx1.riseup.net ([198.252.153.129]:41750) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1gJQiV-0008LF-MU for guix-devel@gnu.org; Sun, 04 Nov 2018 17:18:03 -0500 Received: from piha.riseup.net (piha-pn.riseup.net [10.0.1.163]) (using TLSv1 with cipher ECDHE-RSA-AES256-SHA (256/256 bits)) (Client CN "*.riseup.net", Issuer "COMODO RSA Domain Validation Secure Server CA" (verified OK)) by mx1.riseup.net (Postfix) with ESMTPS id B29CB1A046E for ; Sun, 4 Nov 2018 14:17:57 -0800 (PST) Received: from [127.0.0.1] (localhost [127.0.0.1]) by piha.riseup.net with ESMTPSA id 0438464835 for ; Sun, 4 Nov 2018 14:17:56 -0800 (PST) In-Reply-To: <871s80pka2.fsf@gnu.org> Content-Language: en-US List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: guix-devel@gnu.org This is a multi-part message in MIME format. --------------41EB87F335C10935C21DBE75 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable -------- Forwarded Message -------- Subject: Re: Migration of (dhcp-client-service) Date: Sun, 04 Nov 2018 23:09:25 +0100 From: Ludovic Court=C3=A8s To: swedebugia Hello! swedebugia 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 =E2=80=98service-type=E2=80=99 s= tyle. It=E2=80=99s 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.s= cm? > 2. Are they warned that this is deprecated since 0.16? Currently there=E2=80=99s no deprecation warning (but note that =E2=80=98dhcp-client-service=E2=80=99 is still around.) I=E2=80=99ve been meaning to add a mechanism to emit deprecation warnings= in such cases=E2=80=A6 > 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 > > +++ b/doc/guix.texi > > @@ -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=E2=80=99ve usually just updated the doc to reflect the latest A= PI, even when we kept deprecated APIs around. Not sure if that=E2=80=99s enou= gh; 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=E2=80= =99s what allows us together to improve the code and documentation. Also it=E2=80=99s possible that others had similar questions, so it=E2=80= =99s 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=E2=80=99. --------------41EB87F335C10935C21DBE75 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: quoted-printable
-------- Forwarded Message --------
Sub= ject: Re: Migration of (dhcp-client-service)
Dat= e: Sun, 04 Nov 2018 23:09:25 +0100
Fro= m: Ludovic Court=C3=A8s <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 =E2=80=98service-type=E2=80= =99 style. It=E2=80=99s
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=E2=80=99s no deprecation warning (but note that
=E2=80=98dhcp-client-service=E2=80=99 is still around.)

I=E2=80=99ve been meaning to add a mechanism to emit deprecation wa= rnings in
such cases=E2=80=A6

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=3D=
03fd37b4eb9ec7600c9292361177ca5a47814cf7>
+++ b/doc/guix.texi
<http://git.savannah.gnu.org/cgit/guix.git/tree/doc/guix.texi?id=3D=
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=E2=80=99ve usually just updated the doc to reflect the la= test API,
even when we kept deprecated APIs around. Not sure if that=E2=80=99= 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=E2=80=99s
what allows us together to improve the code and documentation.

Also it=E2=80=99s possible that others had similar questions, so it= =E2=80=99s 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=E2=80=99.
--------------41EB87F335C10935C21DBE75--