Mailing List Archive

[RFC] New QA policy: Packages must not disable installing manpages via USE flags
Hello,

The QA team would like to introduce the following policy:

"""
Packages must not disable installing manpages via USE flags (e.g.
USE=man or USE=doc). If upstream does not ship prebuilt manpages
and building them requires additional dependencies, the maintainer
should build them and ship along with the package.
"""


Explanatory note:

This applies to having USE flags that specifically control building
manpages. It obviously does not affect:

a. USE flags that disable building both a program and its manpage (e.g.
if USE=gui disables building gfrobnicate, not installing gfrobnicate(1)
is correct),

b. use of LINGUAS to control installed manpages.


Rationale:

Manpages are the basic form of user documentation on Gentoo Linux. Not
installing them is harmful to our users. On the other hand, requiring
additional dependencies is inconvenient. Therefore, packaging prebuilt
manpages (whenever upstream doesn't do that already) is a good
compromise that provides user with documentation without additional
dependencies.


What are your comments?

--
Best regards,
Micha? Górny
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
[2019-07-17 15:25:10+0200] Micha? Górny:
> The QA team would like to introduce the following policy:
>
> """
> Packages must not disable installing manpages via USE flags (e.g.
> USE=man or USE=doc). If upstream does not ship prebuilt manpages
> and building them requires additional dependencies, the maintainer
> should build them and ship along with the package.
> """

Should this be for any dependency? For example wlroots, sway, … are
using scdoc to transform a form of markdown to manpages, and the
resulting program is very small.

$ qsize scdoc
app-text/scdoc-1.9.3-r1: 5 files, 12 non-files, 59.9K

So in my opinion if the dependency is probably smaller than bundling
the files the dependency should be used.

> Rationale:
>
> Manpages are the basic form of user documentation on Gentoo Linux. Not
> installing them is harmful to our users. On the other hand, requiring
> additional dependencies is inconvenient. Therefore, packaging prebuilt
> manpages (whenever upstream doesn't do that already) is a good
> compromise that provides user with documentation without additional
> dependencies.

I would fully support that as in my opinion all ebuilds should provide
at least usage documentation though manpages and/or via the
non-standard -h / --help.
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Wed, 2019-07-17 at 15:42 +0200, Haelwenn (lanodan) Monnier wrote:
> [2019-07-17 15:25:10+0200] Micha? Górny:
> > The QA team would like to introduce the following policy:
> >
> > """
> > Packages must not disable installing manpages via USE flags (e.g.
> > USE=man or USE=doc). If upstream does not ship prebuilt manpages
> > and building them requires additional dependencies, the maintainer
> > should build them and ship along with the package.
> > """
>
> Should this be for any dependency? For example wlroots, sway, … are
> using scdoc to transform a form of markdown to manpages, and the
> resulting program is very small.
>
> $ qsize scdoc
> app-text/scdoc-1.9.3-r1: 5 files, 12 non-files, 59.9K
>
> So in my opinion if the dependency is probably smaller than bundling
> the files the dependency should be used.
>

Yes, unconditionally requiring the dependency also fits the proposed
wording.


--
Best regards,
Micha? Górny
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Wed, Jul 17, 2019 at 9:25 AM Micha? Górny <mgorny@gentoo.org> wrote:
>
> Hello,
>
> The QA team would like to introduce the following policy:
>
> """
> Packages must not disable installing manpages via USE flags (e.g.
> USE=man or USE=doc). If upstream does not ship prebuilt manpages
> and building them requires additional dependencies, the maintainer
> should build them and ship along with the package.
> """
>
>
> Explanatory note:
>
> This applies to having USE flags that specifically control building
> manpages. It obviously does not affect:
>
> a. USE flags that disable building both a program and its manpage (e.g.
> if USE=gui disables building gfrobnicate, not installing gfrobnicate(1)
> is correct),
>
> b. use of LINGUAS to control installed manpages.
>
>
> Rationale:
>
> Manpages are the basic form of user documentation on Gentoo Linux. Not
> installing them is harmful to our users. On the other hand, requiring
> additional dependencies is inconvenient. Therefore, packaging prebuilt
> manpages (whenever upstream doesn't do that already) is a good
> compromise that provides user with documentation without additional
> dependencies.
>
>
> What are your comments?

I'm against this.

I seriously doubt maintainers will take the time/effort to pre-build
and distribute manpages. The end result of this will be additional
hard dependencies on heavyweight packages.

I would prefer to give users the choice NOT to install these heavy
packages. If USE=doc is not sufficent, introduce a new flag for it.
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On 2019.07.17 14:25, Micha? Górny wrote:
> Hello,
>
> The QA team would like to introduce the following policy:
>
> """
> Packages must not disable installing manpages via USE flags (e.g.
> USE=man or USE=doc). If upstream does not ship prebuilt manpages
> and building them requires additional dependencies, the maintainer
> should build them and ship along with the package.
> """
>
>
> Explanatory note:
>
> This applies to having USE flags that specifically control building
> manpages. It obviously does not affect:
>
> a. USE flags that disable building both a program and its manpage
> (e.g.
> if USE=gui disables building gfrobnicate, not installing
> gfrobnicate(1)
> is correct),
>
> b. use of LINGUAS to control installed manpages.
>
>
> Rationale:
>
> Manpages are the basic form of user documentation on Gentoo Linux.
> Not
> installing them is harmful to our users. On the other hand, requiring
> additional dependencies is inconvenient. Therefore, packaging
> prebuilt
> manpages (whenever upstream doesn't do that already) is a good
> compromise that provides user with documentation without additional
> dependencies.
>
>
> What are your comments?
>
> --
> Best regards,
> Micha? Górny
>
>

Micha?,

This works on systems with plenty of resources.
I suspect very few arm users have man/doc/info pages installed.
FEATURES="noman nodoc noinfo" is less than ideal as everything
is still built, so you pay the build time, but not installed.

Does anyone read documentation on embedded class hardware?
I know I don't.

Personally, I don't build much on embedded hardware either but I'm
aware of users that do.

I like to have the choice to not build documentation on low power
systems. Its a part of Gentoos flexibility that should not be removed.

--
Regards,

Roy Bamford
(Neddyseagoon) a member of
elections
gentoo-ops
forum-mods
arm64
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Wed, Jul 17, 2019 at 03:25:10PM +0200, Micha? Górny wrote:
> Hello,
>
> The QA team would like to introduce the following policy:
>
> """
> Packages must not disable installing manpages via USE flags (e.g.
> USE=man or USE=doc). If upstream does not ship prebuilt manpages
> and building them requires additional dependencies, the maintainer
> should build them and ship along with the package.
> """
Reading this wording I feel some of the other response have missed the
intent of this policy.

It would be better as two separate policy statements:
"""
Packages must not disable installing manpages via USE flags.
FEATURES=noman should be used to restrict installation of manpages.
"""

The install part I feel is uncontroversial in itself, as it does leave
open that a USE flag could control dependencies & building the manpages
(yes, I'm rules-lawyering).

"""
Package maintainers must build & distribute pre-built manpages IFF
(upstream does not offer them) AND
(building manpages requires build-time additional dependencies)
"""

I agree with the goals of the shipping manpages, but I'm worried about
the requirements it imposes.

- requires the maintainer has some tooling SOMEWHERE to build & package
the manpages. Does this go into the ebuild somehow (e.g. a special
phase)? If not, where else does it get maintained for each package?
- requires a consistent hosting solution for the additional distfiles
created by this change (projects.g.o?).
- significantly increases the version bump requirements (can't simply
copy & local-build & quick-test & commit)
- may require special handling to build & ship manpages in multiple
languages (admittedly very few packages offer non-english manpages).
=> the maintainer now needs to build manpages for ALL possible
languages. This might require the maintainer has lots of locales on
their local system.

--
Robin Hugh Johnson
Gentoo Linux: Dev, Infra Lead, Foundation Treasurer
E-Mail : robbat2@gentoo.org
GnuPG FP : 11ACBA4F 4778E3F6 E4EDF38E B27B944E 34884E85
GnuPG FP : 7D0B3CEB E9B85B1F 825BCECF EE05E6F6 A48F6136
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
Ühel kenal päeval, K, 17.07.2019 kell 18:05, kirjutas Robin H. Johnson:
> - significantly increases the version bump requirements (can't simply
> copy & local-build & quick-test & commit)

Unrelated to the topic at hand, but I seriously hope this isn't the
standard we aim for in our version bumping. At the very least, the
build system should get checked for dependency changes (minimum deps
and otherwise)...


Mart
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Wed, Jul 17, 2019 at 6:25 AM Micha? Górny <mgorny@gentoo.org> wrote:
>
> Hello,
>
> The QA team would like to introduce the following policy:
>
> """
> Packages must not disable installing manpages via USE flags (e.g.
> USE=man or USE=doc).

Xorg libraries use USE=doc to control the build (sometimes) and
installation of thousands of developer-documentation man pages. 99.9%
of the time users don't want the developer man pages installed.

With USE=-doc the packages still install man pages for the
applications, just not the developer documentation man pages.

Is that not reasonable?
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Wed, Jul 17, 2019 at 09:09:47PM +0300, Mart Raudsepp wrote:
> ?hel kenal p?eval, K, 17.07.2019 kell 18:05, kirjutas Robin H. Johnson:
> > - significantly increases the version bump requirements (can't simply
> > copy & local-build & quick-test & commit)
> Unrelated to the topic at hand, but I seriously hope this isn't the
> standard we aim for in our version bumping. At the very least, the
> build system should get checked for dependency changes (minimum deps
> and otherwise)...
Yes, I usually also compare the release vs the previous one, on
upstream's source control, but that's outside the version bump loop in
my terminal. I'd say that's more in the research BEFORE copying
old.ebuild->new.ebuild

--
Robin Hugh Johnson
Gentoo Linux: Dev, Infra Lead, Foundation Treasurer
E-Mail : robbat2@gentoo.org
GnuPG FP : 11ACBA4F 4778E3F6 E4EDF38E B27B944E 34884E85
GnuPG FP : 7D0B3CEB E9B85B1F 825BCECF EE05E6F6 A48F6136
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
I am also against the part of the proposal about maintainer being
responsible to prebuild the docs.

I'd also like to note that Gentoo users are empowered to locally bump
ebuild versions in this insanely easy way, it almost always works, and
it is really useful at times.

With this policy, this instanely easy way will work with lower
probability, because one would need to work around the missing docs
package for the new version.

Also, I don't see how this would work for proxy-maintained packages and
just with external contributions.

Proxies team members have to trust the docs prebuilt by non-devs?
Or they have to build the docs themselves as part of procedure of
acceptance of external contribution?

Perhaps what they can do to stay safe is to sidestep external
contributions which touch such packages.


P.S.

Not a great argument, but I just want to say this: source-based
nature of Gentoo has ingrained the feeling in me that not only
everything is open for studying, but also that, most of time, the result
of package installation on user's machine is "sterile", not tainted by
any interference from middlemen.

I think the currently discussed issue is not critical. Feels odd to
reduce the source-based nature because of that.
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On 2019-07-17 16:56, Mike Gilbert wrote:
> I'm against this.
>
> I seriously doubt maintainers will take the time/effort to pre-build
> and distribute manpages. The end result of this will be additional
> hard dependencies on heavyweight packages.

I second that.

Keep in mind that aside new time requirement for pre-building and
distributing per bump, you often cannot use build system anymore for
installation. For example, please see net-misc/iputils package:
Because it's a base system package, we need to avoid insane doc
dependencies (and this is only xsltproc -- not even the craziest doc
dep hell). Therefore we already ship pre-generated man pages.

But because package provides various USE flags it's becoming a pain to
manually install required docs, see [1]. I don't believe that we want
constructs like that for many packages...


See also:
=========
[1] https://gitweb.gentoo.org/repo/gentoo.git/tree/net-misc/iputils/iputils-99999999.ebuild?id=ec886beb76dc342eec146f7e4d3785437c12bfa9#n159


--
Regards,
Thomas Deutschmann / Gentoo Linux Developer
C4DD 695F A713 8F24 2AA1 5638 5849 7EE5 1D5D 74A5
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Wed, 17 Jul 2019 15:25:10 +0200
Micha? Górny <mgorny@gentoo.org> wrote:

> What are your comments?

I think there's a situation not covered by this prose which is in a bit
of a grey area as per the intentions behind it, (but I would argue is
otherwise fine).

Some systems ship multiple types of documentation, and some, simply
having the package installed means the documentation is available as
the documentation is part of the installed sources.

In the perl ecosystem, if one wants to read documentation for the
installed module "Foo", one only needs to do `perldoc Foo`.

The perl *installer* toolchain however *also* generates manpages with
the extension ".3pm", which we currently *universally* strip, because
they're surplus to requirements, and most users don't expect to use
`man` to read their perl module documentation.

( Perldoc incidentally converts POD to groff on the fly and so its
pretty much identical )

We have exemptions for shipping man-pages for executables, as they
don't get the '.3pm' extension, and they make sense, because then, "I
have /usr/bin/foo, man foo will tell me about it" as an assumption
works fine.

I don't think any of this is "a problem" as such for us, just
suspecting there are other similar cases out there not covered by the
letter of the policy.

In short, the policy suggests that our blanket removal of man pages
is harmful, even though it really isn't the case. ( That is, man pages
for this system are not primary documentation, merely secondary )

That said, we never plan on gating this removal behind a USE flag, it
would create an *impossible* amount of work.
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
Micha? Górny schrieb:
> Packages must not disable installing manpages via USE flags

> a. USE flags that disable building both a program and its manpage

I think it seems an implicit goal that this policy should apply to programs
and their manpages?

In that case, I would suggest to at least limit this policy to man section 1
and 8. As mattst88 explained in another post, X.org developer documentation
in man pages is not interesting for non-developers, and does usually not
describe the functions of a program.


Best regards,
Chí-Thanh Christopher Nguy?n
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Wed, 17 Jul 2019 15:25:10 +0200 Micha? Górny wrote:
> Hello,
>
> The QA team would like to introduce the following policy:
>
> """
> Packages must not disable installing manpages via USE flags (e.g.
> USE=man or USE=doc). If upstream does not ship prebuilt manpages
> and building them requires additional dependencies, the maintainer
> should build them and ship along with the package.
> """
>
>
> Explanatory note:
>
> This applies to having USE flags that specifically control building
> manpages. It obviously does not affect:
>
> a. USE flags that disable building both a program and its manpage (e.g.
> if USE=gui disables building gfrobnicate, not installing gfrobnicate(1)
> is correct),
>
> b. use of LINGUAS to control installed manpages.
>
>
> Rationale:
>
> Manpages are the basic form of user documentation on Gentoo Linux. Not
> installing them is harmful to our users. On the other hand, requiring
> additional dependencies is inconvenient. Therefore, packaging prebuilt
> manpages (whenever upstream doesn't do that already) is a good
> compromise that provides user with documentation without additional
> dependencies.
>
>
> What are your comments?

The basic foundation of Gentoo is freedom of choise for our users.
If installing man pages means no additional dependencies, than
proposed rule is ok. However if such dependencies are required it is
up to users to decide if they wan them or not.

Having USE=man (or USE=doc) for such purposes is fine. Having
USE=man enabled by default in user profile is also fine. Forcing
users to install unnecessary dependencies on minimal systems in a
no go and turns Gentoo into something else.

Best regards,
Andrew Savchenko
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Sat, 2019-07-20 at 20:50 +0300, Andrew Savchenko wrote:
> On Wed, 17 Jul 2019 15:25:10 +0200 Micha? Górny wrote:
> > Hello,
> >
> > The QA team would like to introduce the following policy:
> >
> > """
> > Packages must not disable installing manpages via USE flags (e.g.
> > USE=man or USE=doc). If upstream does not ship prebuilt manpages
> > and building them requires additional dependencies, the maintainer
> > should build them and ship along with the package.
> > """
> >
> >
> > Explanatory note:
> >
> > This applies to having USE flags that specifically control building
> > manpages. It obviously does not affect:
> >
> > a. USE flags that disable building both a program and its manpage (e.g.
> > if USE=gui disables building gfrobnicate, not installing gfrobnicate(1)
> > is correct),
> >
> > b. use of LINGUAS to control installed manpages.
> >
> >
> > Rationale:
> >
> > Manpages are the basic form of user documentation on Gentoo Linux. Not
> > installing them is harmful to our users. On the other hand, requiring
> > additional dependencies is inconvenient. Therefore, packaging prebuilt
> > manpages (whenever upstream doesn't do that already) is a good
> > compromise that provides user with documentation without additional
> > dependencies.
> >
> >
> > What are your comments?
>
> The basic foundation of Gentoo is freedom of choise for our users.
> If installing man pages means no additional dependencies, than
> proposed rule is ok. However if such dependencies are required it is
> up to users to decide if they wan them or not.
>
> Having USE=man (or USE=doc) for such purposes is fine. Having
> USE=man enabled by default in user profile is also fine. Forcing
> users to install unnecessary dependencies on minimal systems in a
> no go and turns Gentoo into something else.
>

Could you please read the proposed policy? It explicitly says you are
*not* supposed to force extra deps on users but build manpages for them.

--
Best regards,
Micha? Górny
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Sat, Jul 20, 2019 at 2:28 PM Micha? Górny <mgorny@gentoo.org> wrote:
>
> Could you please read the proposed policy? It explicitly says you are
> *not* supposed to force extra deps on users but build manpages for them.
>

This seems like a significant increase in maintainer effort compared
to just leaving things as they are for very little benefit. Simple
revbumps turn into needing to do a separate build just to build the
manpages, then package those up, host them somewhere, then fetch and
install that from the ebuild. It would be easier to just make the
whole package a binary package since then all the logic happens
outside the ebuild, and all the ebuild does is fetch/install a
tarball, which it would have to do anyway just for the manpages.

Most packages with stable build systems take almost no effort to
revbump, and this would add a fair bit of complexity. I suspect that
you'll find far more maintainers stop going to the trouble to strip
out the dependencies needed for building manpages vs maintaining two
build systems in parallel, with one having no place to host it.

Then whenever a maintainer disappears the package goes to
maintainer-needed, and anybody who wants to touch it has to figure out
how to build the manpages likely without the benefit of any scripts
the original maintainer had lying around.

If we REALLY wanted to do something like this it seems like it would
be better to build some tooling around it. Maybe an eclass combined
with a special USE flag like "man-build". A daemon would check for
packages that have this IUSE and would build the package using it,
which will generate the manpages. It would then store those pages
using a standardized naming convention. The ebuild would inherit the
eclass which would check if man-build was set, and if not it would
automatically fetch and install the manpages built by the build server
from the mirrors.

Then ebuilds that currently have IUSE=man would just inherit the
eclass and change to the man-build flag. That flag would only be used
by the build servers and not by end users, unless they wanted to build
their own manpages from scratch, which would work fine, as the flag
would not suppress building the rest of the package.

Really though I don't see THAT much benefit from doing either.

--
Rich
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Sat, 20 Jul 2019 20:28:39 +0200 Micha? Górny wrote:
> On Sat, 2019-07-20 at 20:50 +0300, Andrew Savchenko wrote:
> > On Wed, 17 Jul 2019 15:25:10 +0200 Micha? Górny wrote:
> > > Hello,
> > >
> > > The QA team would like to introduce the following policy:
> > >
> > > """
> > > Packages must not disable installing manpages via USE flags (e.g.
> > > USE=man or USE=doc). If upstream does not ship prebuilt manpages
> > > and building them requires additional dependencies, the maintainer
> > > should build them and ship along with the package.
> > > """
> > >
> > >
> > > Explanatory note:
> > >
> > > This applies to having USE flags that specifically control building
> > > manpages. It obviously does not affect:
> > >
> > > a. USE flags that disable building both a program and its manpage (e.g.
> > > if USE=gui disables building gfrobnicate, not installing gfrobnicate(1)
> > > is correct),
> > >
> > > b. use of LINGUAS to control installed manpages.
> > >
> > >
> > > Rationale:
> > >
> > > Manpages are the basic form of user documentation on Gentoo Linux. Not
> > > installing them is harmful to our users. On the other hand, requiring
> > > additional dependencies is inconvenient. Therefore, packaging prebuilt
> > > manpages (whenever upstream doesn't do that already) is a good
> > > compromise that provides user with documentation without additional
> > > dependencies.
> > >
> > >
> > > What are your comments?
> >
> > The basic foundation of Gentoo is freedom of choise for our users.
> > If installing man pages means no additional dependencies, than
> > proposed rule is ok. However if such dependencies are required it is
> > up to users to decide if they wan them or not.
> >
> > Having USE=man (or USE=doc) for such purposes is fine. Having
> > USE=man enabled by default in user profile is also fine. Forcing
> > users to install unnecessary dependencies on minimal systems in a
> > no go and turns Gentoo into something else.
> >
>
> Could you please read the proposed policy? It explicitly says you are
> *not* supposed to force extra deps on users but build manpages for them.

Could you please what the other developers have already replied to
you on this matter? This will be a significant increase in
maintenance burden for both developers and advanced users without
much to gain.

Best regards,
Andrew Savchenko
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Sat, 2019-07-20 at 23:04 +0300, Andrew Savchenko wrote:
> On Sat, 20 Jul 2019 20:28:39 +0200 Micha? Górny wrote:
> > On Sat, 2019-07-20 at 20:50 +0300, Andrew Savchenko wrote:
> > > On Wed, 17 Jul 2019 15:25:10 +0200 Micha? Górny wrote:
> > > > Hello,
> > > >
> > > > The QA team would like to introduce the following policy:
> > > >
> > > > """
> > > > Packages must not disable installing manpages via USE flags (e.g.
> > > > USE=man or USE=doc). If upstream does not ship prebuilt manpages
> > > > and building them requires additional dependencies, the maintainer
> > > > should build them and ship along with the package.
> > > > """
> > > >
> > > >
> > > > Explanatory note:
> > > >
> > > > This applies to having USE flags that specifically control building
> > > > manpages. It obviously does not affect:
> > > >
> > > > a. USE flags that disable building both a program and its manpage (e.g.
> > > > if USE=gui disables building gfrobnicate, not installing gfrobnicate(1)
> > > > is correct),
> > > >
> > > > b. use of LINGUAS to control installed manpages.
> > > >
> > > >
> > > > Rationale:
> > > >
> > > > Manpages are the basic form of user documentation on Gentoo Linux. Not
> > > > installing them is harmful to our users. On the other hand, requiring
> > > > additional dependencies is inconvenient. Therefore, packaging prebuilt
> > > > manpages (whenever upstream doesn't do that already) is a good
> > > > compromise that provides user with documentation without additional
> > > > dependencies.
> > > >
> > > >
> > > > What are your comments?
> > >
> > > The basic foundation of Gentoo is freedom of choise for our users.
> > > If installing man pages means no additional dependencies, than
> > > proposed rule is ok. However if such dependencies are required it is
> > > up to users to decide if they wan them or not.
> > >
> > > Having USE=man (or USE=doc) for such purposes is fine. Having
> > > USE=man enabled by default in user profile is also fine. Forcing
> > > users to install unnecessary dependencies on minimal systems in a
> > > no go and turns Gentoo into something else.
> > >
> >
> > Could you please read the proposed policy? It explicitly says you are
> > *not* supposed to force extra deps on users but build manpages for them.
>
> Could you please what the other developers have already replied to
> you on this matter? This will be a significant increase in
> maintenance burden for both developers and advanced users without
> much to gain.
>

Yes, I get it. User experience is not important if it would mean
developers would actually do anything but the bare minimum to get
from one paycheck to another. The usual Gentoo attitude.

--
Best regards,
Micha? Górny
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Sat, Jul 20, 2019 at 4:22 PM Micha? Górny <mgorny@gentoo.org> wrote:
>
>
> Yes, I get it. User experience is not important if it would mean
> developers would actually do anything but the bare minimum to get
> from one paycheck to another. The usual Gentoo attitude.
>

Not sure where I go to sign up for those paychecks. However, even
employers have to accept that policies have a resource cost to them.

Requiring people to do more than the bare minimum often just ensures
that they won't even bother to do the bare minimum. I'm all for
finding ways to standardize things so that everybody benefits at a
very low cost. This doesn't seem that, and honestly requiring
packages to bundle pre-built manpages seems a bit non-Gentooish to
begin with.

--
Rich
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Sat, 2019-07-20 at 18:16 -0400, Rich Freeman wrote:
> On Sat, Jul 20, 2019 at 4:22 PM Micha? Górny <mgorny@gentoo.org> wrote:
> >
> > Yes, I get it. User experience is not important if it would mean
> > developers would actually do anything but the bare minimum to get
> > from one paycheck to another. The usual Gentoo attitude.
> >
>
> Not sure where I go to sign up for those paychecks. However, even
> employers have to accept that policies have a resource cost to them.
>
> Requiring people to do more than the bare minimum often just ensures
> that they won't even bother to do the bare minimum. I'm all for
> finding ways to standardize things so that everybody benefits at a
> very low cost. This doesn't seem that, and honestly requiring
> packages to bundle pre-built manpages seems a bit non-Gentooish to
> begin with.
>

Then you should go and strip all those pregenerated autotools files,
and require eautoreconf from every single package.

--
Best regards,
Micha? Górny
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Sun, 21 Jul 2019 00:33:00 +0200 Micha? Górny wrote:
> On Sat, 2019-07-20 at 18:16 -0400, Rich Freeman wrote:
> > On Sat, Jul 20, 2019 at 4:22 PM Micha? Górny <mgorny@gentoo.org> wrote:
> > >
> > > Yes, I get it. User experience is not important if it would mean
> > > developers would actually do anything but the bare minimum to get
> > > from one paycheck to another. The usual Gentoo attitude.
> > >
> >
> > Not sure where I go to sign up for those paychecks. However, even
> > employers have to accept that policies have a resource cost to them.
> >
> > Requiring people to do more than the bare minimum often just ensures
> > that they won't even bother to do the bare minimum. I'm all for
> > finding ways to standardize things so that everybody benefits at a
> > very low cost. This doesn't seem that, and honestly requiring
> > packages to bundle pre-built manpages seems a bit non-Gentooish to
> > begin with.
> >
>
> Then you should go and strip all those pregenerated autotools files,
> and require eautoreconf from every single package.

This might be a good idea, actually. Version mismatch between
shipped pregenerated files and system autotools occasionally causes
some problems.

Best regards,
Andrew Savchenko
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Sat, Jul 20, 2019 at 1:22 PM Micha? Górny <mgorny@gentoo.org> wrote:
>
> On Sat, 2019-07-20 at 23:04 +0300, Andrew Savchenko wrote:
> > On Sat, 20 Jul 2019 20:28:39 +0200 Micha? Górny wrote:
> > > On Sat, 2019-07-20 at 20:50 +0300, Andrew Savchenko wrote:
> > > > On Wed, 17 Jul 2019 15:25:10 +0200 Micha? Górny wrote:
> > > > > Hello,
> > > > >
> > > > > The QA team would like to introduce the following policy:
> > > > >
> > > > > """
> > > > > Packages must not disable installing manpages via USE flags (e.g.
> > > > > USE=man or USE=doc). If upstream does not ship prebuilt manpages
> > > > > and building them requires additional dependencies, the maintainer
> > > > > should build them and ship along with the package.
> > > > > """
> > > > >
> > > > >
> > > > > Explanatory note:
> > > > >
> > > > > This applies to having USE flags that specifically control building
> > > > > manpages. It obviously does not affect:
> > > > >
> > > > > a. USE flags that disable building both a program and its manpage (e.g.
> > > > > if USE=gui disables building gfrobnicate, not installing gfrobnicate(1)
> > > > > is correct),
> > > > >
> > > > > b. use of LINGUAS to control installed manpages.
> > > > >
> > > > >
> > > > > Rationale:
> > > > >
> > > > > Manpages are the basic form of user documentation on Gentoo Linux. Not
> > > > > installing them is harmful to our users. On the other hand, requiring
> > > > > additional dependencies is inconvenient. Therefore, packaging prebuilt
> > > > > manpages (whenever upstream doesn't do that already) is a good
> > > > > compromise that provides user with documentation without additional
> > > > > dependencies.
> > > > >
> > > > >
> > > > > What are your comments?
> > > >
> > > > The basic foundation of Gentoo is freedom of choise for our users.
> > > > If installing man pages means no additional dependencies, than
> > > > proposed rule is ok. However if such dependencies are required it is
> > > > up to users to decide if they wan them or not.
> > > >
> > > > Having USE=man (or USE=doc) for such purposes is fine. Having
> > > > USE=man enabled by default in user profile is also fine. Forcing
> > > > users to install unnecessary dependencies on minimal systems in a
> > > > no go and turns Gentoo into something else.
> > > >
> > >
> > > Could you please read the proposed policy? It explicitly says you are
> > > *not* supposed to force extra deps on users but build manpages for them.
> >
> > Could you please what the other developers have already replied to
> > you on this matter? This will be a significant increase in
> > maintenance burden for both developers and advanced users without
> > much to gain.
> >
>
> Yes, I get it. User experience is not important if it would mean
> developers would actually do anything but the bare minimum to get
> from one paycheck to another. The usual Gentoo attitude.

I don't understand your reaction, but it's very common with
predictable steps to generate it:

1) You make a proposal
2) People offer feedback and ask questions
3) You respond combatively (or not at all), as if you are upset that
people perhaps are not 100% aligned with your view.

... which honestly shouldn't be at all unexpected and is precisely why
requesting comments on a proposal is valuable.

My question earlier in the thread is relevant and still unaddressed.
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Wed, 2019-07-17 at 12:09 -0700, Matt Turner wrote:
> On Wed, Jul 17, 2019 at 6:25 AM Micha? Górny <mgorny@gentoo.org> wrote:
> > Hello,
> >
> > The QA team would like to introduce the following policy:
> >
> > """
> > Packages must not disable installing manpages via USE flags (e.g.
> > USE=man or USE=doc).
>
> Xorg libraries use USE=doc to control the build (sometimes) and
> installation of thousands of developer-documentation man pages. 99.9%
> of the time users don't want the developer man pages installed.
>
> With USE=-doc the packages still install man pages for the
> applications, just not the developer documentation man pages.
>
> Is that not reasonable?

I think it's a reasonable compromise.

--
Best regards,
Micha? Górny
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On Sat, 20 Jul 2019 22:22:39 +0200
Micha? Górny <mgorny@gentoo.org> wrote:

> Yes, I get it. User experience is not important if it would mean
> developers would actually do anything but the bare minimum to get
> from one paycheck to another. The usual Gentoo attitude.

You of course realise putting more demands on The Process of existing
developers, who are in short supply, and their time is also in short
supply, will, ultimately result in a detriment to the userbase, by
virtue of them becoming less capable to achieve the same volume of
tasks?

Its one thing to make this a policy, which I think on the _surface_ is
fine, but this one hints towards substantial changes we don't currently
have tooling support to streamline.

Maybe think about how we can empower developers to achieve this, and
then after it becomes remotely practical to do this _at scale_, we make
it policy to do so?

Yes, yes, I'm suggesting something perverted like a build server or
system for aggregating built man-pages on gentoo-servers automatically
as part of CI, that end users can just trivially fetch. But that's just
one approach, surely, there are others.
Re: [RFC] New QA policy: Packages must not disable installing manpages via USE flags [ In reply to ]
On 21-07-2019 23:47:02 +1200, Kent Fredric wrote:
> Yes, yes, I'm suggesting something perverted like a build server or
> system for aggregating built man-pages on gentoo-servers automatically
> as part of CI, that end users can just trivially fetch. But that's just
> one approach, surely, there are others.

Right, or we go for some (official) form of binpkgs distribution.

Fabian

--
Fabian Groffen
Gentoo on a different level

1 2  View All