Subject: Re: [bug#77204] [PATCH v4 0/3] dnsmasq service changes

From: Maxim Cournoyer <[email-masked]>
Date: Fri, 16 May 2025 22:04:05 +0900

Hi Alexey!

Alexey Abramov <[email-masked]> writes:

> Thank you, Maxim, for your thorough review.  With v4 I did address all
> your suggestions (I hope I didn't miss anything ;)).

Thank you!

> I had an impression that `M-q' would do a proper formating of
> sentences, but apparently `sentence-end-double-space' is a hint to
> just break lines.  Am i missing something?

That's what it does for me.  I do use paredit-mode, which rebinds this
to paredit-reindent-defun.

> Regarding the commit messages, I kinda used to go to diff in magit and
> press `C' on a hunk and it does add things to the commit message.  I
> did check git log and see people use different ways like (), [] and
> <>.  Seems like a more personal stuff, but I would like to know
> more...

You are right that there are various preferences/dialect in use.  [ ]
are documented as for conditional changes, but we use that in Guix to
denote record's fields.  (info "(standards) Style of Change Logs") has
more examples about it.  Some people like to preserve the hierarchy of
things, e.g.

--8<---------------cut here---------------start------------->8---
[arguments] <#:phases>: Add X phases.
--8<---------------cut here---------------end--------------->8---

Some others prefer to flatten things a bit:

--8<---------------cut here---------------start------------->8---
[phases] {patch-commands}: New phase.
--8<---------------cut here---------------end--------------->8---

Both are acceptable in my opinion, as long as it is unambiguous.

> With these v4 series:
>
>  - I moved documentation of actions to the manual and not in the action
>    procedures themselves.  herd doc prints texi markups as is.
>
>  - I removed indentation of fields.

Sounds good.  I've done a few light touch ups/rewording in the change
logs/documentation, such as:

> Alexey Abramov (3):
>   services: dnsmasq: Add shepherd-provision and shepherd-requirement
>     fields.
>   services: dnsmasq: Add pid-file, conf-file and conf-dir configuration
>     fields.

--8<---------------cut here---------------start------------->8---
modified   doc/guix.texi
@@ -36305,16 +36305,14 @@ DNS Services
 network or obtained a DHCP lease from dnsmasq.
 
 @item @code{conf-file} (default: @code{'()})
-Specify a configuration file or multiple.  The given value should be a
-list of string paths to the configuration files.  File-like objects are
-also supported.
+File names of configuration files to use.  Strings and file-like objects
+are accepted.
 
 @item @code{conf-dir} (default: @code{#f})
 Read all the files in the given directory as configuration files.
-@command{dnsmasq} also supports extensions for the field, but here it is
-not implemented.  It is more convenient to make @code{computed-file}
-directory in the store and use that.  Files are loaded in alphabetical
-order of filename.
+Support for @command{dnsmasq} field extensions is not implemented; users
+can use @code{computed-file} to build a directory of files instead.  The
+configuration files are loaded in alphabetical order of file name.
 
 @item @code{extra-options} (default: @code{'()})
 This option provides an ``escape hatch'' for the user to provide arbitrary
--8<---------------cut here---------------end--------------->8---

>   services: dnsmasq: Add stats and reload shepherd actions.

--8<---------------cut here---------------start------------->8---
modified   doc/guix.texi
@@ -36121,21 +36121,24 @@ DNS Services
 
 @itemize @bullet
 @item
-Clears the DNS cache
+Clear the DNS cache
 @item
-Reloads @file{/etc/hosts} and @file{/etc/ethers}
+Reload @file{/etc/hosts} and @file{/etc/ethers}
 @item
-Reloads files specified by @option{--dhcp-hostsfile}, @option{--dhcp-hostsdir},
+Reload files specified by @option{--dhcp-hostsfile}, @option{--dhcp-hostsdir},
 @option{--dhcp-optsfile}, @option{--dhcp-optsdir}, @option{--addn-hosts},
 or @option{--hostsdir}
 @item
-Executes DHCP lease change scripts for all existing leases
+Execute DHCP lease change scripts for all existing leases
 @item
-Rereads @file{/etc/resolv.conf} (only if @option{--no-poll} is configured)
+Reread @file{/etc/resolv.conf} (only if @option{--no-poll} is
+configured).
 @end itemize
 
-@emph{Note:} The @code{SIGHUP} signal does not trigger a reread of the main
+@quotation Note
+The @code{SIGHUP} signal does not trigger a reload of the main
 configuration file.
+@end quotation
 
 Example usage:
 @example
@@ -36154,7 +36157,7 @@ DNS Services
 @item
 For each upstream server: queries sent and errors received
 @item
-TCP connection fork statistics
+TCP connection fork statistics.
 @end itemize
 
 Example usage:
modified   gnu/tests/networking.scm
@@ -680,7 +680,7 @@ (define %test-dhcpd
 
 
 ;;;
-;;; dnsmasq tests
+;;; dnsmasq tests.
 ;;;
--8<---------------cut here---------------end--------------->8---

And pushed!  Thank you!

-- 
Maxim