Re: Regarding MESSAGEs during pkg_add installation of meta packages

[David Holland <dholland-pkgtech%netbsd.org@localhost>]

On Thu, Apr 03, 2025 at 10:38:35AM -0400, Greg Troxel wrote:
 > > 1. Sometimes there are cases where it's fairly important to include a
 > > message of the form "When updating from 2.x to 3.x you need to
 > > re-reticulate all the splines or thingy-gui won't start". The current
 > > MESSAGE infrastructure is a poor way to handle this. However, I don't
 > > think we want to replace it with _no_ way to handle this. Ideally
 > > these would be indexed by version number so they only get displayed
 > > when applicable.
 > 
 > The previous documentation was that MESSAGE should be used only for
 > lasting negative consequences.  So far we do not have an example where
 > that is applicable.

"I ran pkg_rr and my webserver broke and I had to spend all evening
chasing it down instead of doing what I meant to do, which was
updating this other package people care about" -- whether that counts
as "lasting" is debatable (the time someone had to do something
productive was permanently wasted, but the productive thing can still
happen later) but I don't think it's the sort of thing we should allow
to happen unnecessarily.

 > A package where you need to do such manual things on upgrade to get it
 > to work has an upstream bug, and of course many packages do.  We ask
 > that NEWS be in commit messages - but people often commit without
 > adequate NEWS.  There is of course pgsql and mongo (and I think mysql*)
 > where you have to dump/restore across major versions.  There is
 > nextcloud where you have to manually initiate upgrade migrations.  I
 > hypothesize that these sorts of migration pain points are in large
 > packages where those using them need to read the upstream documentation
 > anyway.

Right right, but there are plenty of opportunities for this kind of
thing to come up _in a package I don't really know about_. I install
apache and php-spifflication and postgres, I expect to have to
administer them. (All the same it's better for any non-routine tasks
to be specifically annunciated.)

However, I don't necessarily even notice that php-spifflication
depends indirectly on php-ftagn, and it turns out that updating
php-ftagn from 6.6 to 6.66 requires adjusting the apache config.  If
there's a MESSAGE-like scheme (though as noted, MESSAGE is completely
inadequate as is) there's a chance that this point might be brought to
my attention. Without one, there's just about zero chance that I'll
notice a mention buried in a commit message for a package I know
nothing about.

And if I don't notice, my installation breaks when I update and it
will probably take some time to figure out why. Then (depending on
who "I" am) I might come here to reiterate the above points, or just
complain, or grumble on irc, or possibly just go around telling people
that pkgsrc sucks.

So, basically, I entirely disagree. There are a few things one should
know about, like dumping your databases before a postgres major
update, but most update tasks of this form are once-offs caused by
upstream issues. And in an environment where maybe 10% of the packages
that one has has installed are packages one knows much about or pays
attention to, it's unreasonable to expect users to pay close attention
to, or even necessary particularly notice, any specific update.

 > I'd like to talk about actual cases, thinking that there are few to
 > none.

grep update */*/MESSAGE reveals half a dozen or so, e.g. in majordomo.
While most of them are probably now stale, it does demonstrate that
these cases exist.

 > > 2. Moving the assorted glop that exists in most MESSAGEs to a
 > > README.pkgsrc is fine, but when that stuff matters it's probably a
 > > good idea to specifically point users at it. This applies, for
 > > example, when you need to install other things to get a properly
 > > functional package. (Whether such cases should exist is another
 > > debate; for the time being they do.) The same alternative notice
 > > system as (1) should serve. Ideally these notices would also be
 > > indexed such that they only appear when installing for the first time.
 > 
 > That is what DESCR is for: to describe what is in the package.  And,
 > therefore what is not in the package but might be expected.  The case
 > you describe is a package that is sort of split into base and plugins
 > (often sound), but we have chosen not to have any dependencies.

Again, this ignores the issue that the package might be something I
don't particularly know or care about that's there because something I
_do_ care about is using it.

Also, I'm not sure that I agree DESCR is the place for stuff like "you
need to install ffmpeg". It's better than _nothing_ but that's not
saying much.

I think a better plan would be a README.pkgsrc file that goes in a
predictable place _and_ a notice pointing at it when it contains stuff
you need to act on to get a working package.

As pointed out elsethread upstream docs are not always adequate or
portable.

 > There are a lot of DESCR that have upstream marketing text and don't
 > explain what is in the package.  This has been often a problem when we
 > have multiple versions.  I have fixed many of these over the years.

No disagreement on that.

 > > Also, there are some things where the default config you need has to
 > > go in $HOME, so dealing with that problem isn't quite as simple as
 > > just using CONF_FILES.
 > 
 > I think the expectation is that upstream should document how to use the
 > program, that the docs are in the distfile, that pkgsrc installs the
 > docs, and that users read the docs before using the program.  I do not
 > think it is wise or reasonable to go off plan from that.

That also only works for things one specifically intends to use and
installs manually.

-- 
David A. Holland
dholland%netbsd.org@localhost