[gentoo-dev] Useless messages (elog, ewarn, etc) in ebuilds

[gentoo-dev] Useless messages (elog, ewarn, etc) in ebuilds

[Amadeusz Żołnowski]

[-- Attachment #1: Type: text/plain, Size: 3120 bytes --]

Hi,

I'd like to call our attention to messages printed by ebuilds for users
(elog, ewarn, and so on).  We all know that users rarely read them, but
this is understandable, since most of them are *completely* useless,
most of the rest are confusing, and only couple of them are useful.  Who
has time to read tens of messages to find one useful sentence?  I try to
skim all messages and check if there's something new, but if some
package has message which fill whole screen and requires from user to
make several checks there is almost 100% chance that this new important
message is going to be skipped.

I'd like to encourage users to fill bugs wrt useless or confusing
messages.

There are several kind of messages:

1) "If you are upgrading from X to Y, then do Z."

I see this message in some packages even I have already version Y or later
installed.  We have "has_version" function to check if user has actually
updated from relevant version.  Please use this to not confuse users who
installed the package first time or are upgrading from Y to another
version.

2) "We no longer do something and do something else."

This is case similar to (1).  We can check if user has upgraded between
versions bringing the changes we want call their attention to.

3) "You can install Y to have support for Z."

This actually is optional dependencies problem, but we can unify
printing the list at least.  For example:

* Optional dependencies:
*
*  category1/pkg1 - description1
*  category2/pkg2 - description2

4) "If you are using baselayout-2, be sure to add Y to runlevel Z."
5) "Y has been removed.  Please remove it from your runlevels."

We can easily check if user has added Y to runlevel Z.  If this is
critical that user has to add Y to runlevel Z, then an ebuild should add
it itself and inform user about that.  If it is not critical it should
inform user that Y could be added to runlevel Z only if installed first
time, not every upgrade.  Same applies to removal - it can be done by an
ebuild.

6) "USE flag noY is deprecated, please use Y."

Cannot we check if user has enabled noY?  At least we can check if
he/she enabled Y.

7) "If you use Y, do something."

We can check if Y flag is enabled or Y package is installed and skip the
message if it is not.

8) "Example configuration file has been installed to Y."

We can check if user has already configured a package (check
existence of a config file or its modification time).

9) "Run revdep-rebuild."

We can check if package has been upgraded at least and skip the message
if it has been installed first time or the same version has been
reinstalled.

10) "Y config file has been moved to Z. If you have made changes to Y,
migrate them to Z."

We can check that in the ebuild and skip message if hasn't done anything
to the config file.

11) "If something happens, install Y."

We can at least check if Y is already installed.

*) Other kind of information which appears after EVERY installation.

All howtos should go to Gentoo Docs!


-- 
Amadeusz Żołnowski

[-- Attachment #2: signature --]
[-- Type: application/pgp-signature, Size: 490 bytes --]

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)

iQEcBAABAgAGBQJQM4wpAAoJEPATRTHh2/q1v8kIAKBreCWNsa5zr8fVGiSjsoCL
pb8zE3sv59WXTQDsQaBQX2tMWMgA7ZhPD9R+IQw2ydRBHCRgWPNadd/MFJpHK3/T
EtCPo61l9m++ZRYqOWNl+LOJZa6KgPu5X2ruuhwylF1pkqQYnMhHQQpVqFww91yD
Jy5oQdrOiQG0J0C5Q23nx+7m57VevQVRKMOVGjCgtWVY9MgNl+0ULayLWWEd4KUt
ZcGdtu0O7Q1bIkAVfUXvq7FRFKWiAkPfT31kqO80TN45dGVMsXNw4q+Yh1CN4Byw
zwNK4C/Q7UsZAkVNcKI65IZsst3ewWtC9ZLJ/+xCPO7lUf1RbbesIet0Rv2lpmQ=
=iKQs
-----END PGP SIGNATURE-----

Re: [gentoo-dev] Useless messages (elog, ewarn, etc) in ebuilds

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 1235 bytes --]

On Tue, 21 Aug 2012 15:24:57 +0200
Amadeusz Żołnowski <aidecoe@gentoo.org> wrote:
> We have "has_version" function to check if user has
> actually updated from relevant version.  Please use this to not
> confuse users who installed the package first time or are upgrading
> from Y to another version.

Doing it using has_version isn't really recommended, since...

...if EAPIs before 2 are involved, the order of pkg_ functions on an
upgrade, reinstall or downgrade might not be what you expect.

...the behaviour of has_version in the case of upgrades, reinstalls or
downgrades may not be what you expect.

...the behaviour of has_version in the case of upgrades, reinstalls or
downgrades is not what it used to be due to a non-EAPI-controlled
change in behaviour from Portage, meaning some documentation and
examples are now wrong, and the way you used to do it doesn't work any
more.

...an upgrade can result in the removal of two versions of a package,
not just one, if slots have changed.

It's thus much better to use REPLACING_VERSIONS (which is plural, and
this is important) rather than has_version, if you're asking about the
current package rather than another package.

-- 
Ciaran McCreesh

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] Useless messages (elog, ewarn, etc) in ebuilds

[Amadeusz Żołnowski]

[-- Attachment #1: Type: text/plain, Size: 884 bytes --]

Quoting Ciaran McCreesh (2012-08-21 15:35:38)
> On Tue, 21 Aug 2012 15:24:57 +0200 Amadeusz Żołnowski
> <aidecoe@gentoo.org> wrote:
> > We have "has_version" function to check if user has actually updated
> > from relevant version.  Please use this to not confuse users who
> > installed the package first time or are upgrading from Y to another
> > version.
> 
> Doing it using has_version isn't really recommended, since...
>
> [...]
> 
> It's thus much better to use REPLACING_VERSIONS (which is plural, and
> this is important) rather than has_version, if you're asking about the
> current package rather than another package.

Right.  Thanks.  REPLACING_VERSIONS and REPLACED_BY_VERSION is much
better, but for older EAPIs couldn't one set it manually with help of
has_version in pkg_setup and check that var later in postinst?.

-- 
Amadeusz Żołnowski

[-- Attachment #2: signature --]
[-- Type: application/pgp-signature, Size: 490 bytes --]

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)

iQEcBAABAgAGBQJQM5JCAAoJEPATRTHh2/q1ZaQH/jGrk4yqTCktl4OMUNbUWz5u
n41ZVTNLwSr8UhkVYTyxXS3sQaiFVRz3WrBmGtI6x0vG5TnFgwoxx/lqpd/RImXt
hlQ2FH3RqFW23oJLIxlfyJrOW/bbRxH5tLagh88pAMKKnoaDiLuVAf6GPIFmOing
wcYKWnPiVoWRAQ4SJIMkPEDN43BwFuHPUywMr6IfpfBaf3sh0b4qjUjFPexA6k3H
ngveCXVXY2afmaqdHFQK1AHr7J0Uv09vuDjYhJ6Gpbq+a1Bm2jjDMPZwhFD3+NbA
9+MlfjiiyvTn3/QbKNaQaqhedopjLAJdOGP7e+uVRdMZZg9I2B1Qf4PulAdaEXg=
=lXoN
-----END PGP SIGNATURE-----

Re: [gentoo-dev] Useless messages (elog, ewarn, etc) in ebuilds

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 714 bytes --]

On Tue, 21 Aug 2012 15:50:58 +0200
Amadeusz Żołnowski <aidecoe@gentoo.org> wrote:
> > It's thus much better to use REPLACING_VERSIONS (which is plural,
> > and this is important) rather than has_version, if you're asking
> > about the current package rather than another package.
> 
> Right.  Thanks.  REPLACING_VERSIONS and REPLACED_BY_VERSION is much
> better, but for older EAPIs couldn't one set it manually with help of
> has_version in pkg_setup and check that var later in postinst?.

One could, but one probably shouldn't, unless one is familiar with
the exact rules for env saving with binary packages... We added
REPLACING_VERSIONS to make this kind of thing easy.

-- 
Ciaran McCreesh

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]