svn commit: r53135 - head/en_US.ISO8859-1/books/porters-handbook/pkg-files

[Mathieu Arnold]

Author: mat
Date: Tue Jun 11 13:00:57 2019
New Revision: 53135
URL: https://svnweb.freebsd.org/changeset/doc/53135

Log:
  Add guidelines for when to add a pkg-message.
  
  Submitted by:	adamw
  Reviewed by:	adamw, bapt
  Differential Revision:	https://reviews.freebsd.org/D20578

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml	Tue Jun 11 08:23:17 2019	(r53134)
+++ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml	Tue Jun 11 13:00:57 2019	(r53135)
@@ -18,11 +18,26 @@
   <sect1 xml:id="porting-message">
     <title><filename>pkg-message</filename></title>
 
-    <para>To display a message when the package is installed,
-      place the message in <filename>pkg-message</filename>.  This
+    <para>To display a message when the package is installed, place
+      the message in <filename>pkg-message</filename>.  This
       capability is often useful to display additional installation
-      steps to be taken after a <command>pkg install</command> or to
-      display licensing information.</para>
+      steps to be taken after a <command>pkg install</command> or
+      <command>pkg upgrade</command>.</para>
+
+    <important>
+      <para><filename>pkg-message</filename> must contain only
+	information that is <emphasis>vital</emphasis> to setup and
+	operation on &os;, and that is unique to the port in
+	question.</para>
+
+      <para>Setup information should only be shown on initial install.
+	Upgrade instructions should be shown only when upgrading from
+	the relevant version.</para>
+
+      <para>Committers have blanket approval to constrain existing
+	messages to install or upgrade ranges using the
+	<acronym>UCL</acronym> format specifications.</para>
+    </important>
 
     <para>pkg-message supports two formats:</para>