CVS commit: pkgsrc/doc/guide/files

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

Module Name:    pkgsrc
Committed By:   wiz
Date:           Thu Apr 17 22:00:11 UTC 2025

Modified Files:
        pkgsrc/doc/guide/files: Makefile chapters.ent pkgsrc.xml
Added Files:
        pkgsrc/doc/guide/files: policies.xml

Log Message:
Document new pkgsrc stability policy.


To generate a diff of this commit:
cvs rdiff -u -r1.22 -r1.23 pkgsrc/doc/guide/files/Makefile
cvs rdiff -u -r1.20 -r1.21 pkgsrc/doc/guide/files/chapters.ent
cvs rdiff -u -r1.44 -r1.45 pkgsrc/doc/guide/files/pkgsrc.xml
cvs rdiff -u -r0 -r1.1 pkgsrc/doc/guide/files/policies.xml

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

Modified files:

Index: pkgsrc/doc/guide/files/Makefile
diff -u pkgsrc/doc/guide/files/Makefile:1.22 pkgsrc/doc/guide/files/Makefile:1.23
--- pkgsrc/doc/guide/files/Makefile:1.22        Fri Oct  1 17:20:27 2021
+++ pkgsrc/doc/guide/files/Makefile     Thu Apr 17 22:00:11 2025
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.22 2021/10/01 17:20:27 nia Exp $
+# $NetBSD: Makefile,v 1.23 2025/04/17 22:00:11 wiz Exp $
 
 WEB_PREFIX?=           ${.CURDIR}/../htdocs
 DBX_XML_CATALOG?=      ${SGML_PREFIX}/docbook/4.5/catalog.xml
@@ -35,6 +35,7 @@ SRCS+=        options.xml
 SRCS+= pkginstall.xml
 SRCS+= platforms.xml
 SRCS+= plist.xml
+SRCS+= policies.xml
 SRCS+= porting.xml
 SRCS+= regression.xml
 SRCS+= submit.xml

Index: pkgsrc/doc/guide/files/chapters.ent
diff -u pkgsrc/doc/guide/files/chapters.ent:1.20 pkgsrc/doc/guide/files/chapters.ent:1.21
--- pkgsrc/doc/guide/files/chapters.ent:1.20    Fri Oct  1 17:20:27 2021
+++ pkgsrc/doc/guide/files/chapters.ent Thu Apr 17 22:00:11 2025
@@ -1,7 +1,7 @@
 <!--
        Creates entities for each chapter in the pkgsrc book.
 
-       $NetBSD: chapters.ent,v 1.20 2021/10/01 17:20:27 nia Exp $
+       $NetBSD: chapters.ent,v 1.21 2025/04/17 22:00:11 wiz Exp $
 -->
 
 <!ENTITY chap.intro                    SYSTEM "introduction.xml">
@@ -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: pkgsrc/doc/guide/files/pkgsrc.xml
diff -u pkgsrc/doc/guide/files/pkgsrc.xml:1.44 pkgsrc/doc/guide/files/pkgsrc.xml:1.45
--- pkgsrc/doc/guide/files/pkgsrc.xml:1.44      Wed Jan  1 01:39:11 2025
+++ pkgsrc/doc/guide/files/pkgsrc.xml   Thu Apr 17 22:00:11 2025
@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<!-- $NetBSD: pkgsrc.xml,v 1.44 2025/01/01 01:39:11 jnemeth Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.45 2025/04/17 22:00:11 wiz Exp $ -->
 
 <!DOCTYPE book PUBLIC "-//NetBSD//DTD DocBook XML V4.5-Based DocBook Extension//EN" [
 
@@ -47,7 +47,7 @@
       <holder role="mailto:www%NetBSD.org@localhost";>The NetBSD Foundation, Inc</holder>
     </copyright>
 
-    <pubdate>$NetBSD: pkgsrc.xml,v 1.44 2025/01/01 01:39:11 jnemeth Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.45 2025/04/17 22:00:11 wiz Exp $</pubdate>
 
     <abstract>
 
@@ -98,6 +98,7 @@
     &chap.fixes;
     &chap.gnome;
     &chap.submit;
+    &chap.policies;
     &chap.devfaq;
   </part>
 

Added files:

Index: pkgsrc/doc/guide/files/policies.xml
diff -u /dev/null pkgsrc/doc/guide/files/policies.xml:1.1
--- /dev/null   Thu Apr 17 22:00:12 2025
+++ pkgsrc/doc/guide/files/policies.xml Thu Apr 17 22:00:11 2025
@@ -0,0 +1,56 @@
+<!-- $NetBSD: policies.xml,v 1.1 2025/04/17 22:00:11 wiz 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, pkgsrc-pmc marks 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 packages marked
+  with <varname>POLICY_UPDATE_LIMITED=abi</varname>, 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, i.e. marked with
+  <varname>POLICY_UPDATE_LIMITED=bootstrap</varname>, 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>