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