Re: policy proposal: updating packages with many dependencies

[Thomas Klausner <wiz%NetBSD.org@localhost>]

With attachment this time, I hope.

On Fri, Apr 11, 2025 at 10:30:11AM +0200, Thomas Klausner wrote:
> Here's the updated policy, which adds a section about bootstrap
> packages.
> 
> I plan to remove the explicit list of packages from the guide once
> pkglint has support for the to-be-introduced flag, and the packages
> have been marked.
> 
> What is the list for the bootstrap category?
> 
> I've removed 'rust' from the ABI category, because it has a different
> set of tests we usually would like to have, more focusing on
> portability than the result of a bulk build; and I don't want to have
> sections that contain just one package. We can add a section for it
> and similar packages later.
>  Thomas

Index: guide/files/Makefile
===================================================================
RCS file: /cvsroot/pkgsrc/doc/guide/files/Makefile,v
retrieving revision 1.22
diff -u -r1.22 Makefile
--- guide/files/Makefile	1 Oct 2021 17:20:27 -0000	1.22
+++ guide/files/Makefile	11 Apr 2025 08:27:48 -0000
@@ -35,6 +35,7 @@
 SRCS+=	pkginstall.xml
 SRCS+=	platforms.xml
 SRCS+=	plist.xml
+SRCS+=	policies.xml
 SRCS+=	porting.xml
 SRCS+=	regression.xml
 SRCS+=	submit.xml
Index: guide/files/chapters.ent
===================================================================
RCS file: /cvsroot/pkgsrc/doc/guide/files/chapters.ent,v
retrieving revision 1.20
diff -u -r1.20 chapters.ent
--- guide/files/chapters.ent	1 Oct 2021 17:20:27 -0000	1.20
+++ guide/files/chapters.ent	11 Apr 2025 08:27:48 -0000
@@ -33,6 +33,7 @@
 <!ENTITY chap.submit			SYSTEM "submit.xml">
 <!ENTITY chap.devfaq			SYSTEM "devfaq.xml">
 <!ENTITY chap.gnome			SYSTEM "gnome.xml">
+<!ENTITY chap.policies			SYSTEM "policies.xml">
 
 <!-- The pkgsrc infrastructure -->
 <!ENTITY chap.infr.design		SYSTEM "infr.design.xml">
Index: guide/files/pkgsrc.xml
===================================================================
RCS file: /cvsroot/pkgsrc/doc/guide/files/pkgsrc.xml,v
retrieving revision 1.44
diff -u -r1.44 pkgsrc.xml
--- guide/files/pkgsrc.xml	1 Jan 2025 01:39:11 -0000	1.44
+++ guide/files/pkgsrc.xml	11 Apr 2025 08:27:48 -0000
@@ -98,6 +98,7 @@
     &chap.fixes;
     &chap.gnome;
     &chap.submit;
+    &chap.policies;
     &chap.devfaq;
   </part>
 
Index: guide/files/policies.xml
===================================================================
RCS file: guide/files/policies.xml
diff -N guide/files/policies.xml
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ guide/files/policies.xml	11 Apr 2025 08:27:48 -0000
@@ -0,0 +1,61 @@
+<!-- $NetBSD: submit.xml,v 1.42 2024/10/11 20:21:27 jkoshy Exp $ -->
+
+<chapter id="policies"> <?dbhtml filename="policies.html"?>
+<title>pkgsrc Policies</title>
+
+<sect1 id="stability">
+<title>Packages for which updating is restricted</title>
+
+<para>In the past, some packages have caused more package failures than others, and we'd like to reduce this in the future.</para>
+
+<para>For this reason, we mark some packages with <varname>POLICY_UPDATE_LIMITED</varname>. The possible values currently are:
+<itemizedlist>
+  <listitem><para><literal>abi</literal> for packages where ABI/API changes often broke the packages depending on them </para></listitem>
+  <listitem><para><literal>bootstrap</literal> for packages that are used during the pkgsrc bootstrap</para></listitem>
+</itemizedlist>
+<filename>pkglint</filename> will warn when committing updates to these packages.</para>
+
+<sect2 id="stability.abi">
+  <title>Limited Updates - ABI</title>
+
+<para>Before committing non-micro version updates to any of the following
+packages:
+<itemizedlist>
+  <listitem><para><filename role="pkg">devel/boost*</filename></para></listitem>
+  <listitem><para><filename role="pkg">lang/erlang</filename></para></listitem>
+  <listitem><para><filename role="pkg">textproc/icu</filename></para></listitem>
+  <listitem><para><filename role="pkg">lang/llvm</filename></para></listitem>
+  <listitem><para><filename role="pkg">print/poppler</filename></para></listitem>
+</itemizedlist>
+</para>
+<para>a limited bulk build of <filename
+role="pkg">meta-pkgs/bulk-test-${PACKAGE}</filename> needs to be run
+and the result posted to the tech-pkg mailing list, highlighting what
+packages would stop building (if any).</para>
+
+<para>Depending on the result, pkgsrc-pmc then decides:
+<itemizedlist>
+  <listitem><para>go ahead with the update</para></listitem>
+  <listitem><para>wait for packages X, Y, Z to be fixed (upstream or locally) with the
+  updated version, which is put in wip in the meantime</para></listitem>
+  <listitem><para>In the second case, all pkgsrc developers are encouraged to work on
+  fixing this - it is not only the updater's task to fix them.</para></listitem>
+</itemizedlist>
+</para>
+
+<para>The decision to wait for packages can be revisited.</para>
+
+</sect2>
+
+<sect2 id="stability.bootstrap">
+  <title>Limited Updates - Bootstrap</title>
+
+  <para>When updating packages used in the bootstrap, test the bootstrap process and
+  preferably some basic packages and send the patch to the tech-pkg mailing list so it
+  can be tested on other platforms as well. Give at least two weeks for
+  feedback and testing by others.</para>
+</sect2>
+
+</sect1>
+
+</chapter>