<section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="sec-release-19.03">
 <title>Release 19.03</title>

 <para>
  The 19.03 release branch became the stable branch in April, 2019.
 </para>

 <section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="sec-release-19.03-highlights">
  <title>Highlights</title>

  <para>
   This release has the following notable changes:
  </para>

  <itemizedlist>
   <listitem>
    <para>
     The <option>home.file.&lt;name?&gt;.source</option> now allows source
     files to be hidden, that is, having a name starting with the
     <literal>.</literal> character. It also allows the source file name to
     contain characters not typically allowed for Nix store paths. For example,
     your configuration can now contain things such as
<programlisting>
home.file."my file".source = ./. + "/file with spaces!";
</programlisting>
    </para>
   </listitem>
   <listitem>
    <para>
     The type used for the systemd unit options under
     <option>systemd.user.services</option>,
     <option>systemd.user.sockets</option>, etc. has been changed to offer more
     robust merging of configurations. If you don't override values within
     systemd units then you are not affected by this change. Unfortunately, if
     you do override unit values you may encounter errors.
    </para>
    <para>
     In particular, if you get an error saying that a <quote>unique
     option</quote> is <quote>defined multiple times</quote> then you need to
     use the
     <code xlink:href="https://nixos.org/nixos/manual/#sec-option-definitions-setting-priorities">mkForce</code>
     function. For example,
<programlisting language="nix">
systemd.user.services.foo.Service.ExecStart = "/foo/bar";
</programlisting>
     becomes
<programlisting language="nix">
systemd.user.services.foo.Service.ExecStart = lib.mkForce "/foo/bar";
</programlisting>
     We had to make this change because the old merging was causing too many
     confusing situations for people.
    </para>
   </listitem>
  </itemizedlist>
 </section>

 <section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="sec-release-19.03-state-version-changes">
  <title>State Version Changes</title>

  <para>
   The state version in this release includes the changes below. These changes
   are only active if the <option>home.stateVersion</option> option is set to
   "19.03" or later.
  </para>

  <itemizedlist>
   <listitem>
    <para>
     There is now an option <option>programs.beets.enable</option> that
     defaults to <literal>false</literal>. Before the module would be active if
     the <option>programs.beets.settings</option> option was non-empty.
    </para>
   </listitem>
  </itemizedlist>
 </section>
</section>