From fee1838470a56f3f5595dfd949ec01010e85c96e Mon Sep 17 00:00:00 2001
From: Bill Allombert <Bill.Allombert@math.u-bordeaux.fr>
Date: Mon, 6 Jun 2011 20:30:34 +0200
Subject: [PATCH] Perl policy: Document major version upgrade trigger

Wording: Dominic Hargreaves <dom@debian.org>
Seconded: Russ Allbery <rra@debian.org>
Seconded: Niko Tyni <ntyni@debian.org>
Seconded: Gregor Herrmann <gregoa@debian.org>
Closes: #619275
---
 debian/changelog         |  8 +++++++-
 perl-policy.sgml         | 20 ++++++++++++++++++++
 upgrading-checklist.sgml |  4 ++++
 3 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/debian/changelog b/debian/changelog
index 4de31e5..a580f7f 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -35,8 +35,14 @@ debian-policy (3.9.3.0) UNRELEASED; urgency=low
     Seconded: Bill Allombert <ballombe@debian.org>
     Seconded: Jakub Wilk <jwilk@debian.org>
     Closes: #617516
+  * Perl policy: Document major version upgrade trigger
+    Wording: Dominic Hargreaves <dom@debian.org>
+    Seconded: Russ Allbery <rra@debian.org>
+    Seconded: Niko Tyni <ntyni@debian.org>
+    Seconded: Gregor Herrmann <gregoa@debian.org>
+    Closes: #619275
 
- -- Bill Allombert <ballombe@debian.org>  Mon, 06 Jun 2011 19:51:39 +0200
+ -- Bill Allombert <ballombe@debian.org>  Wed, 08 Jun 2011 23:01:20 +0200
 
 debian-policy (3.9.2.0) unstable; urgency=low
 
diff --git a/perl-policy.sgml b/perl-policy.sgml
index b9f3277..70c5bfc 100644
--- a/perl-policy.sgml
+++ b/perl-policy.sgml
@@ -461,6 +461,26 @@ perl -MExtUtils::Embed -e ldopts
 	  package must depend upon it explicitly.
 	</p>
       </sect>
+
+      <sect id="perl_upgrades">
+        <heading>Perl Package Upgrades</heading>
+        <p>
+          Starting from <package>perl</package> 5.12.3-2, a dpkg trigger
+          named <var>perl-major-upgrade</var> will be triggered by the
+          postinst of the <package>perl</package> package during major
+          upgrades. Some examples of things which constitute a major upgrade
+          are an upgrade which would change the value of versioned
+          directories in <tt>@INC</tt>, or one which changes <tt>abiname</tt>.
+          Any package may declare an interest in the trigger, especially
+          packages including long-running daemons which would stop working
+          until restart.
+        </p>
+        <p>
+          It is suggested that such packages include an appropriate section
+          in their postinst to handle the trigger by restarting relevant
+          daemons or notifying users of further action.
+        </p>
+      </sect>
     </chapt>
 
     <appendix id="perl6">
diff --git a/upgrading-checklist.sgml b/upgrading-checklist.sgml
index 22eacb3..95ab9d2 100644
--- a/upgrading-checklist.sgml
+++ b/upgrading-checklist.sgml
@@ -50,6 +50,10 @@ Unreleased.
   of normal rules for non-free dependencies and were largely obsolete, so
   they have been removed.
   </item>
+<tag>perl</tag>
+  <item> Packages may declare an interest in the <var>perl-major-upgrade</var> 
+  trigger to be notified of major upgrades of perl.
+  </item>
 </taglist></p>
 
 <sect> Version 3.9.2.0
-- 
2.39.2