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

classic Classic list List threaded Threaded
50 messages Options
123
Reply | Threaded
Open this post in threaded view
|

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

Michał Górny-5
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


signature.asc (631 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

haelwenn (lanodan) Monnier
[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.

Reply | Threaded
Open this post in threaded view
|

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

Michał Górny-5
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


signature.asc (631 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Mike Gilbert-2
In reply to this post by Michał Górny-5
On Wed, Jul 17, 2019 at 9:25 AM Michał Górny <[hidden email]> 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.

Reply | Threaded
Open this post in threaded view
|

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

Roy Bamford-2
In reply to this post by Michał Górny-5
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

attachment0 (499 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Robin H. Johnson-2
In reply to this post by Michał Górny-5
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   : [hidden email]
GnuPG FP : 11ACBA4F 4778E3F6 E4EDF38E B27B944E 34884E85
GnuPG FP : 7D0B3CEB E9B85B1F 825BCECF EE05E6F6 A48F6136

signature.asc (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Mart Raudsepp-2
Ü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

signature.asc (1000 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Matt Turner-5
In reply to this post by Michał Górny-5
On Wed, Jul 17, 2019 at 6:25 AM Michał Górny <[hidden email]> 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?

Reply | Threaded
Open this post in threaded view
|

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

Robin H. Johnson-2
In reply to this post by Mart Raudsepp-2
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   : [hidden email]
GnuPG FP : 11ACBA4F 4778E3F6 E4EDF38E B27B944E 34884E85
GnuPG FP : 7D0B3CEB E9B85B1F 825BCECF EE05E6F6 A48F6136

signature.asc (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Andrey Utkin-3
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.

signature.asc (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Thomas Deutschmann
In reply to this post by Mike Gilbert-2
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


signature.asc (631 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Kent Fredric-2
In reply to this post by Michał Górny-5
On Wed, 17 Jul 2019 15:25:10 +0200
Michał Górny <[hidden email]> 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.

attachment0 (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Chí-Thanh Christopher Nguyễn
In reply to this post by Michał Górny-5
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

Reply | Threaded
Open this post in threaded view
|

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

Andrew Savchenko
In reply to this post by Michał Górny-5
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

attachment0 (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Michał Górny-5
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


signature.asc (631 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Rich Freeman
On Sat, Jul 20, 2019 at 2:28 PM Michał Górny <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

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

Andrew Savchenko
In reply to this post by Michał Górny-5
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

attachment0 (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Michał Górny-5
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


signature.asc (631 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Rich Freeman
On Sat, Jul 20, 2019 at 4:22 PM Michał Górny <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

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

Michał Górny-5
On Sat, 2019-07-20 at 18:16 -0400, Rich Freeman wrote:

> On Sat, Jul 20, 2019 at 4:22 PM Michał Górny <[hidden email]> 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


signature.asc (631 bytes) Download Attachment
123