Bug#1033511: release-notes: mention the switch from old polkit .pkla files to JavaScript .rules

[Simon McVittie <smcv@debian.org>]

Package: release-notes
Severity: normal
Control: affects -1 src:policykit-1
X-Debbugs-Cc: policykit-1@packages.debian.org

I think the transition mentioned in /usr/share/doc/polkitd/NEWS.Debian.gz
deserves to be included in the bookworm release notes. I attach some
possible wording. I'm not entirely sure which section this should go
in, so the location suggested below is only a guess: please move it
as necessary.

Note that I've included a link to the bookworm polkit(8) man page, but
the version displayed on manpages.debian.org is currently wrong (it
seems to be a cached version of the man page as it appeared in bullseye).
I've reported a separate bug. If the manpages.d.o bug is not fixed by
the time this is ready for merge, then a workaround would be to link
to the unstable version of polkit(8), which has the correct content.

    smcv

diff --git a/en/issues.dbk b/en/issues.dbk
index 4b7b9dda..38e79ce9 100644
--- a/en/issues.dbk
+++ b/en/issues.dbk
@@ -55,6 +55,54 @@
 
     </section>
 
+    <section id="polkitd-pkla">
+      <!-- bullseye to bookworm -->
+      <title>polkit .pkla files deprecated</title>
+      <para>
+        polkit (formerly PolicyKit) has been upgraded from version 0.105 to
+        version 122.
+        This version changes the syntax used for local policy rules:
+        it is now the same JavaScript-based format used by the upstream polkit
+        project and by other Linux distributions.
+      </para>
+      <para>
+        System administrators can override the default security policy by
+        installing local policy overrides into
+        <filename>/etc/polkit-1/rules.d/*.rules</filename>,
+        which can either make the policy more restrictive or more
+        permissive.
+        Some sample policy rules can be found in the
+        <filename>/usr/share/doc/polkitd/examples</filename> directory.
+        Please see the <ulink
+          url="&url-man;/&releasename;/polkitd/polkit.8.html#AUTHORIZATION_RULES">polkit(8)
+          manual page</ulink> for more details.
+      </para>
+      <para>
+        Older Debian releases used the "local authority" rules format from
+        upstream version 0.105, consisting of <literal>.pkla</literal>
+        files with a <literal>.desktop</literal>-like syntax,
+        installed into subdirectories of
+        <filename>/etc/polkit-1/localauthority</filename>
+        or <filename>/var/lib/polkit-1/localauthority</filename>.
+        The <systemitem role="package">polkitd-pkla</systemitem> package
+        provides compatibility with these files, and will usually be
+        installed during upgrades.
+        If it is installed, then <literal>.pkla</literal> files will be
+        processed at a higher priority than most <literal>.rules</literal>
+        files.
+        If the <systemitem role="package">polkitd-pkla</systemitem>
+        package is removed, <literal>.pkla</literal> files will no longer
+        be used.
+      </para>
+      <para>
+        The <literal>.pkla</literal> files should be considered deprecated,
+        and <systemitem role="package">polkitd-pkla</systemitem> is likely
+        to be removed in a future Debian release.
+        Please migrate any local policy overrides to the JavaScript format
+        after upgrading.
+      </para>
+    </section>
+
     <section id="puppetserver">
       <!-- bullseye to bookworm -->
       <title>Puppet configuration management system upgraded to 7</title>