tech-pkg archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

Re: Regarding MESSAGEs during pkg_add installation of meta packages



My read of comments is that we have rough consensus to deprecate
MESSAGE, with some concern that there might in theory be a situation
where MESSAGE is critically useful.  We don't have any identified cases
(and in my read-MESSAGE-think-about-removing-it actions over the years,
I haven't found one).

Therefore I think we're heading to say it's deprecated, to attempt to
clean up 99% of the uses, and then see what's left.

I have drafted a guide change, to note deprecation and request cleanup
of all MESSAGE content, with any valid content under the current
"lasting harm" doctrine to be reported for discussion.

Patch at end, and new text first, because diffs of xml are not easy to
read.

----------------------------------------
MESSAGE

    This file is displayed after installation of the package. While this was
    used often in the past, it has multiple problems:

      + the display will be missed if many packages are installed at once

      + the person installing the package may be different than the one
        responsible for configuring it

      + the installation may be scripted by automation tools

      + it is often used to display information that is redundant with
        documentation, or should be documentation

    Previous doctrine was that it should be used only in exceptional
    circumstances where lasting negative consequences would result from someone
    not reading it. As of 2025-03, MESSAGE is deprecated, based on rough
    consensus. Situations that would result in lasting negative consquences
    should be reported to pkgsrc email lists. Deprecation means that no new
    MESSAGE files may be added, and no content may be added to any existing
    file.

    With deprecation, maintainers are asked to remove MESSAGE files, simply
    dropping the following categories:

      + exhortations to read the documentation

      + reminders to install rc.d files and set variables

      + suggestions to configure syslog file rotation

    Explanations that the package does not work without other packages should
    be moved to DESCR, which is documented to describe what the package does
    (and therefore does not) contain.

    Content that is an explanation of how to use the package in a pkgsrc
    context (but is not applicable to a person building the package from
    upstream without pkgsrc) should be placed in e.g. files/README.pkgsrc and
    installed in in the package's documentation directory.

    Content that belongs in upstream documentation, e.g. because it is useful
    to someone building and using the software from upstream sources, should be
    submitted upstream. It may be placed in files/README.pkgsrc but should be
    marked as belonging upstream.

    After 2025-05-01, anyone should feel free to remediate MESSAGE files, even
    if there is a MAINTAINER/OWNER.

    Until deprecation is complete:

      + Note that MESSAGE is shown for all operating systems and all init
        systems. If a MESSAGE is necessary, it should be narrowed to only those
        operating systems and init systems to which it applies.

      + Note that you can modify variables in it easily by using MESSAGE_SUBST
        in the package's Makefile

      + You can display a different or additional files by setting the
        MESSAGE_SRC variable.
----------------------------------------

Index: doc/guide/files/components.xml
===================================================================
RCS file: /cvsroot/pkgsrc/doc/guide/files/components.xml,v
retrieving revision 1.65
diff -u -p -r1.65 components.xml
--- doc/guide/files/components.xml	11 Oct 2024 19:46:56 -0000	1.65
+++ doc/guide/files/components.xml	3 Apr 2025 14:39:07 -0000
@@ -600,50 +600,78 @@ FILES_SUBST+=  SOMEVAR="somevalue"
 
 	  <listitem>
 	    <para>This file is displayed after installation of the package.
-	    While this was used often in the past, it has two
-	    problems: the display will be missed if many packages are
-	    installed at once, and the person installing the package
-	    and the one using or configuring it may be different.  It
-	    should therefore be used only in exceptional circumstances
-	    where lasting negative consequences would result from
-	    someone not reading it.</para>
-	    <para>MESSAGE should not be used for:</para>
+	    While this was used often in the past, it has multiple problems:
+	    <itemizedlist>
+	      <listitem><para>the display will be missed if many
+   	      packages are installed at once</para></listitem>
+	      <listitem><para>the person installing the package may be
+	      different than the one responsible for configuring
+	      it</para></listitem>
+	      <listitem><para>the installation may be scripted by
+	      automation tools</para></listitem>
+	      <listitem><para>it is often used to display information
+	      that is redundant with documentation, or should be
+	      documentation</para></listitem>
+	    </itemizedlist>
+	    Previous doctrine was that it should be used only in
+	    exceptional circumstances where lasting negative
+	    consequences would result from someone not reading it.  As
+	    of 2025-03, MESSAGE is deprecated, based on rough
+	    consensus.  Situations that would result in lasting
+	    negative consquences should be reported to pkgsrc email
+	    lists.  Deprecation means that no new MESSAGE files may be
+	    added, and no content may be added to any existing file.
+	    </para>
+	    <para>With deprecation, maintainers are asked to remove
+	    MESSAGE files, simply dropping the following categories:
 	    <itemizedlist>
 	      <listitem><para>exhortations to read the documentation</para></listitem>
 	      <listitem><para>reminders to install rc.d files and set variables</para></listitem>
-	      <listitem><para>anything that should be explained in the
-	      installation/configuration documentation that should
-	      come with the package</para></listitem>
+	      <listitem><para>suggestions to configure syslog file rotation</para></listitem>
 	    </itemizedlist>
-	    <para>If the documentation provided by upstream needs
-	    enhancing, create e.g. files/README.pkgsrc and install it
-	    in the package's documentation directory.
-	    </para>
-	    <para>Note that MESSAGE is shown for all operating
-	    systems and all init systems.  If a MESSAGE is necessary,
-	    it should be narrowed to only those operating systems and
-	    init systems to which it applies.</para>
-	    <para>Note that you can modify variables in it easily by using
-	    <varname>MESSAGE_SUBST</varname> in the package's
-	    <filename>Makefile</filename>:</para>
-
-<programlisting>
-MESSAGE_SUBST+=  SOMEVAR="somevalue"
-</programlisting>
-
-	    <para>replaces "${SOMEVAR}" with <quote>somevalue</quote> in
-	    <filename>MESSAGE</filename>.  By default, substitution is
-	    performed for <varname>PKGNAME</varname>,
-	    <varname>PKGBASE</varname>, <varname>PREFIX</varname>,
-	    <varname>LOCALBASE</varname>, <varname>X11BASE</varname>,
-	    <varname>PKG_SYSCONFDIR</varname>,
-	    <varname>ROOT_GROUP</varname>, and
-	    <varname>ROOT_USER</varname>.</para>
-
-	    <para>You can display a different or additional files by
-	    setting the <varname>MESSAGE_SRC</varname> variable.  Its
-	    default is <filename>MESSAGE</filename>, if the file
-	    exists.</para>
+	    </para>
+	    <para>
+	    Explanations that the package does not work without other
+	    packages should be moved to <filename>DESCR</filename>,
+	    which is documented to describe what the package does (and
+	    therefore does not) contain.
+	    </para>
+	    <para>
+	    Content that is an explanation of how to use the package
+	    in a pkgsrc context (but is not applicable to a person
+	    building the package from upstream without pkgsrc) should
+	    be placed in e.g. <filename>files/README.pkgsrc</filename>
+	    and installed in in the package's documentation directory.
+	    </para>
+	    <para>
+	    Content that belongs in upstream documentation,
+	    e.g. because it is useful to someone building and using
+	    the software from upstream sources, should be submitted
+	    upstream.  It may be placed in
+	    <filename>files/README.pkgsrc</filename> but should be
+	    marked as belonging upstream.
+	    </para>
+	    <para>
+	      After 2025-05-01, anyone should feel free to remediate
+	      MESSAGE files, even if there is a MAINTAINER/OWNER.
+	    </para>
+	    <para>Until deprecation is complete:
+	    <itemizedlist>
+	      <listitem><para>Note that MESSAGE is shown for all
+	      operating systems and all init systems.  If a MESSAGE is
+	      necessary, it should be narrowed to only those operating
+	      systems and init systems to which it
+	      applies.</para></listitem>
+	      <listitem><para>Note that you can modify variables in it
+	      easily by using <varname>MESSAGE_SUBST</varname> in the
+	      package's
+	      <filename>Makefile</filename></para></listitem>
+	      <listitem><para>You can display a different or
+	      additional files by setting the
+	      <varname>MESSAGE_SRC</varname>
+	      variable.</para></listitem>
+	    </itemizedlist>
+	    </para>
 	  </listitem>
 	</varlistentry>
 



Home | Main Index | Thread Index | Old Index