Following the discussion around devmanual and policies, I've started a new draft project: Policy Guide. Rendering: https://dev.gentoo.org/~mgorny/tmp/policy-guide/ Source: https://github.com/mgorny/policy-guide-draft Not to repeat too much, the idea is to have a separate guide that documents all QA (and other project) policies, split from devmanual (that's focused on teaching and goes beyond policies) and organized in more scalable, indexed form. I've used Sphinx as that's probably the simplest tool to achieve the goal. Right now it's just in tmp and on my GitHub account but if it's approved, I'm going to move it to move permanent locations on Gentoo Infra. Right now it uses the default 'alabaster' Sphinx theme. It's got a little bug with horizontal lists with narrow screens but let's ignore that for now. I've already started asking around for Tyrian-ish Sphinx theme, so hopefully we'll get something more consistent with other Gentoo docs. I've already pre-filled it with some policies to demonstrate how it'd look like. All policies from the wiki page were copied there (so we can retire that), as well as some other policies pointed out by developers on #gentoo-qa. I'd like to call for a two-fold vote. Firstly, vote on whether we want to go for this Policy Guide in general and document future policies there. Secondly, clarification vote on all the policies so far, as many of them never received a formal vote and I'd like to clear this once and for all. Please vote by answering two questions: 1. Do you agree with introducing a Policy Guide? Yes/no + possible comments. 2. Do you agree with the currently documented policies? If no, please link the policies you disagree with. If we get majority on 1., Policy Guide becomes official. If any policy is disagreed on in 2. by a majority of QA members, I'll bring it up for rediscussing before the Guide is published.
1. yes 2. yes
2. I disagree on https://dev.gentoo.org/~mgorny/tmp/policy-guide/use-flags.html#use-gui-flag. What was discussed in the mailing list was introduction of a "gui" flag. The policy in the guide seems to suggest that USE="X" will be forbidden, which isn't feasible for packages that can use more than one window systems (e.g. "X" and "aqua").
(In reply to Ulrich Müller from comment #2) > 2. I disagree on > https://dev.gentoo.org/~mgorny/tmp/policy-guide/use-flags.html#use-gui-flag. > > What was discussed in the mailing list was introduction of a "gui" flag. The > policy in the guide seems to suggest that USE="X" will be forbidden, which > isn't feasible for packages that can use more than one window systems (e.g. > "X" and "aqua"). I don't see how you read "USE=X will be forbidden" from that.
(In reply to David Seifert from comment #3) > I don't see how you read "USE=X will be forbidden" from that. "Whenever a package offers an optional GUI support, the gui flag must be used to control that support rather than historically used X or toolkit flags." That implies that packages *must* use the "gui" flag now, and that they *must not* use the "X" flag. Or at least, that's how I am reading it. And this makes no sense and should be dropped.
Besides, I don't think that QA should be micro-managing single USE flags.
(In reply to Ulrich Müller from comment #5) > Besides, I don't think that QA should be micro-managing single USE flags. Disagree, we do it for USE=ssl/ffmpeg/imagemagick for a pleasant globally consistent UX. If a package optionally supports ONE gui toolkit that uses motif, then correct, you should use USE=gui for that and not the more historical USE=X. On the other hand, if a package supports both Gtk3 and Motif (not very realistic, but to make the point), then you can use USE="gui gtk3 X" and RDEPEND="gui? ( X? ( x11-libs/motif ) gtk3? ( x11-libs/gtk+:3 ) )" The whole point of USE=gui is to be self-explanatory. What does USE="X wayland" do? Does +X +wayland enable just wayland? Does -X disable the gui? Is it obvious? No. It's been agreed that USE=gui is something we want and in a similar vein to USE=ssl/ffmpeg/imagemagick.
(In reply to David Seifert from comment #6) > Disagree, we do it for USE=ssl/ffmpeg/imagemagick for a pleasant globally > consistent UX. If a package optionally supports ONE gui toolkit that uses > motif, then correct, you should use USE=gui for that and not the more > historical USE=X. > On the other hand, if a package supports both Gtk3 and > Motif (not very realistic, but to make the point), then you can use USE="gui > gtk3 X" and RDEPEND="gui? ( X? ( x11-libs/motif ) gtk3? ( x11-libs/gtk+:3 ) > )" Now that doesn't make much sense. If a package supports both gtk3 and motif then it should have IUSE="gtk3 motif". Why would anyone use "X" for motif? These are different layers, X and Wayland are window systems, and on top of them you can have toolkits like GTK, QT, or Motif. > The whole point of USE=gui is to be self-explanatory. What does USE="X > wayland" do? Does +X +wayland enable just wayland? Does -X disable the gui? Sorry, but what is one supposed to do if a package can support either of them? Does USE="gui" enable X, or does it enable Wayland? I'm not convinced that the "gui" flag will be self-explanatory in that situation.
(In reply to Ulrich Müller from comment #2) > 2. I disagree on > https://dev.gentoo.org/~mgorny/tmp/policy-guide/use-flags.html#use-gui-flag. > > What was discussed in the mailing list was introduction of a "gui" flag. The > policy in the guide seems to suggest that USE="X" will be forbidden, which > isn't feasible for packages that can use more than one window systems (e.g. > "X" and "aqua"). That was merely referring to historical cases of using USE=X to indicate 'build some GUI'. I've seen that on a few packages, and 1) it's redundant to USE=gui, 2) it's confusing when GUI works for X11 and Wayland, 3) it collides with other specialized of uses of X11.
1. yes 2. yes (I do not see the problem with the X use flag par reading, I mean, probably I read as it was supposed to be).
(In reply to Ulrich Müller from comment #7) > (In reply to David Seifert from comment #6) > > Disagree, we do it for USE=ssl/ffmpeg/imagemagick for a pleasant globally > > consistent UX. If a package optionally supports ONE gui toolkit that uses > > motif, then correct, you should use USE=gui for that and not the more > > historical USE=X. > > On the other hand, if a package supports both Gtk3 and > > Motif (not very realistic, but to make the point), then you can use USE="gui > > gtk3 X" and RDEPEND="gui? ( X? ( x11-libs/motif ) gtk3? ( x11-libs/gtk+:3 ) > > )" > > Now that doesn't make much sense. If a package supports both gtk3 and motif > then it should have IUSE="gtk3 motif". Why would anyone use "X" for motif? > > These are different layers, X and Wayland are window systems, and on top of > them you can have toolkits like GTK, QT, or Motif. > > > The whole point of USE=gui is to be self-explanatory. What does USE="X > > wayland" do? Does +X +wayland enable just wayland? Does -X disable the gui? > > Sorry, but what is one supposed to do if a package can support either of > them? Does USE="gui" enable X, or does it enable Wayland? I'm not convinced > that the "gui" flag will be self-explanatory in that situation. Again, like USE="ssl". It controls **optional** use of a GUI. USE="-gui" disables an optional GUI. Whether USE="gui X wayland" enable X wayland, both, or one of them isn't resolved by this, just like USE="ssl openssl gnutls" won't tell you whether an application chooses openssl or gnutls as ssl backend. On the other hand USE="-ssl openssl gnutls" definitely disables SSL. Here's the text I wrote initially for this: USE="gui" ========= Policy: If a package *optionally* supports building a GUI, it should use USE="gui" to enable support for this. This policy is tangential to how dependencies should be specified if multiple GUI toolkits are supported. EXAMPLE 1: * Package supports only GTK 3, and requires it unconditionally. Trivial case, no gui in IUSE. IUSE="" DEPEND/RDEPEND="x11-libs/gtk+:3" EXAMPLE 2: * Package supports GTK 3 optionally. Also easy, if and only if the package supports one toolkit only. IUSE="gui" DEPEND/RDEPEND="gui? ( x11-libs/gtk+:3 )" EXAMPLE 3: * Package supports GTK 3 and Qt 5, but requires at least one of them. No gui in IUSE, as support is not optional. For DEPEND/RDEPEND, maintainers can use REQUIRED_USE or use-cascades for discrimianting between mutually exclusive toolkits (which is not addressed by this policy). EXAMPLE 4: * Package supports GTK 3 and Qt 5, but can also be used without a toolkit. IUSE="gui" plus the gtk3 and qt5 use flags too. Whether you're using REQUIRED_USE or use-cascades, both should be guarded by a gui? conditionally. This has the advantage of avoiding potentially ugly blocker for pure terminal users. REQUIRED_USE="gui? ( ^^ ( gtk3 qt5 ) )" will not fire for USE="-gui" where gtk3 was defaulted to on and qt5 might have been enabled globally. Rationale: Historically, Gentoo has used various flags which would have enabled optional GUI support. USE="X/gtk/qt" have all been used, and for all of them it wasn't always clear whether they pull in libX11 or just enable the GUI for instance. USE=gui is self-documenting and acts in a way similar to USE=ssl, which also enables optional SSL support.
leio suggesting it: https://archives.gentoo.org/gentoo-dev/message/eecad370248118c474a0d819fa7f3576 andrey_utkin requesting it: https://archives.gentoo.org/gentoo-dev/message/624f0e33a8dd581d4b81b3b8ae582610
(In reply to David Seifert from comment #10) > EXAMPLE 1: > * Package supports only GTK 3, and requires it unconditionally. > > Trivial case, no gui in IUSE. > > IUSE="" > DEPEND/RDEPEND="x11-libs/gtk+:3" That case seems to be clear. > EXAMPLE 2: > * Package supports GTK 3 optionally. > > Also easy, if and only if the package supports one toolkit only. > > IUSE="gui" > DEPEND/RDEPEND="gui? ( x11-libs/gtk+:3 )" Here the confusion already starts. Does the package use X, and gtk3 is only enabled on top of it? I'd argue that X11 without a toolkit still qualifies as a GUI (as opposed to a CLI). > EXAMPLE 3: > * Package supports GTK 3 and Qt 5, but requires at least one of them. > > No gui in IUSE, as support is not optional. For DEPEND/RDEPEND, maintainers > can use REQUIRED_USE or use-cascades for discrimianting between mutually > exclusive toolkits (which is not addressed by this policy). OK. > EXAMPLE 4: > * Package supports GTK 3 and Qt 5, but can also be used without a toolkit. > > IUSE="gui" plus the gtk3 and qt5 use flags too. Whether you're using > REQUIRED_USE or use-cascades, both should be guarded by a gui? > conditionally. This has the advantage of avoiding potentially ugly blocker > for pure terminal users. REQUIRED_USE="gui? ( ^^ ( gtk3 qt5 ) )" will not > fire for USE="-gui" where gtk3 was defaulted to on and qt5 might have been > enabled globally. Again, what does "without a toolkit" mean? That's exactly the situation with app-editors/emacs, which has "gtk athena motif" in IUSE, but can also run on bare X11 without any toolkit. In other words, is USE="gui" supposed to enable the window system (i.e., replace the "X" and "aqua" flags), or is it supposed to enable an optional toolkit on top of that window system? Apparently is cannot have both purposes at the same time.
(In reply to Ulrich Müller from comment #12) > (In reply to David Seifert from comment #10) > > EXAMPLE 1: > > * Package supports only GTK 3, and requires it unconditionally. > > > > Trivial case, no gui in IUSE. > > > > IUSE="" > > DEPEND/RDEPEND="x11-libs/gtk+:3" > > That case seems to be clear. > > > EXAMPLE 2: > > * Package supports GTK 3 optionally. > > > > Also easy, if and only if the package supports one toolkit only. > > > > IUSE="gui" > > DEPEND/RDEPEND="gui? ( x11-libs/gtk+:3 )" > > Here the confusion already starts. Does the package use X, and gtk3 is only > enabled on top of it? I'd argue that X11 without a toolkit still qualifies > as a GUI (as opposed to a CLI). > > > EXAMPLE 3: > > * Package supports GTK 3 and Qt 5, but requires at least one of them. > > > > No gui in IUSE, as support is not optional. For DEPEND/RDEPEND, maintainers > > can use REQUIRED_USE or use-cascades for discrimianting between mutually > > exclusive toolkits (which is not addressed by this policy). > > OK. > > > EXAMPLE 4: > > * Package supports GTK 3 and Qt 5, but can also be used without a toolkit. > > > > IUSE="gui" plus the gtk3 and qt5 use flags too. Whether you're using > > REQUIRED_USE or use-cascades, both should be guarded by a gui? > > conditionally. This has the advantage of avoiding potentially ugly blocker > > for pure terminal users. REQUIRED_USE="gui? ( ^^ ( gtk3 qt5 ) )" will not > > fire for USE="-gui" where gtk3 was defaulted to on and qt5 might have been > > enabled globally. > > Again, what does "without a toolkit" mean? That's exactly the situation with > app-editors/emacs, which has "gtk athena motif" in IUSE, but can also run on > bare X11 without any toolkit. > > In other words, is USE="gui" supposed to enable the window system (i.e., > replace the "X" and "aqua" flags), or is it supposed to enable an optional > toolkit on top of that window system? Apparently is cannot have both > purposes at the same time. Enable an optional GUI part. If emacs supports raw libX11 to produce a GUI (yikes!), then USE="-gui" should disable that too. "USE=gui enables any optional GUI support", and in this case, building against raw libX11 enables optional GUI support. That is, USE=-gui should definitely not pull in libX11. USE=gui is a feature USE flag, separate from an impl USE flag (which X, aqua, motif, athena, gtk3, qt5 then become). Currently, USE=X is used to enable X vs aqua in some ebuilds, and to enable optional GUI support in others (and "raw X11" counts as "optional GUI support"). If you're unhappy with the wording, suggest improvements.
Answers: 1.Yes 2.Yes Thank you (In reply to Michał Górny from comment #0) > Following the discussion around devmanual and policies, I've started a new > draft project: Policy Guide. > > Rendering: > https://dev.gentoo.org/~mgorny/tmp/policy-guide/ > Source: > https://github.com/mgorny/policy-guide-draft > > Not to repeat too much, the idea is to have a separate guide that documents > all QA (and other project) policies, split from devmanual (that's focused on > teaching and goes beyond policies) and organized in more scalable, indexed > form. I've used Sphinx as that's probably the simplest tool to achieve the > goal. Right now it's just in tmp and on my GitHub account but if it's > approved, I'm going to move it to move permanent locations on Gentoo Infra. > > Right now it uses the default 'alabaster' Sphinx theme. It's got a little > bug with horizontal lists with narrow screens but let's ignore that for now. > I've already started asking around for Tyrian-ish Sphinx theme, so hopefully > we'll get something more consistent with other Gentoo docs. > > I've already pre-filled it with some policies to demonstrate how it'd look > like. All policies from the wiki page were copied there (so we can retire > that), as well as some other policies pointed out by developers on > #gentoo-qa. > > I'd like to call for a two-fold vote. Firstly, vote on whether we want to > go for this Policy Guide in general and document future policies there. > Secondly, clarification vote on all the policies so far, as many of them > never received a formal vote and I'd like to clear this once and for all. > > Please vote by answering two questions: > > 1. Do you agree with introducing a Policy Guide? Yes/no + possible comments. > > 2. Do you agree with the currently documented policies? If no, please link > the policies you disagree with. > > If we get majority on 1., Policy Guide becomes official. If any policy is > disagreed on in 2. by a majority of QA members, I'll bring it up for > rediscussing before the Guide is published.
(In reply to Ulrich Müller from comment #2) > 2. I disagree on > https://dev.gentoo.org/~mgorny/tmp/policy-guide/use-flags.html#use-gui-flag. I vote yes on 1. and on the rest of 2.
1. yes. 2. yes. UnCC-ing all people who voted already.
Even without dilfridge's vote we have a majority on both questions, that is: 1. 5 yes, 0 no, 1 waiting, so it passes. 2. USE=gui 4 yes, 1 no, 1 waiting, so it passes. other points 5 yes, 0 no, 1 waiting, so it passes. I'm going to start preparing infra for this.
git@git.gentoo.org:proj/policy-guide.git set up and pushed current content. GitHub mirror @ https://github.com/gentoo/policy-guide set up. Also Bugzilla component Documentation → Policy Guide added. The next question is how we publish the generated content. We could use Gentoo Infra (like devmanual), GitHub pages, RTD... @infra, this is a Sphinx project. Any suggestions? Note that I use tox to build it since in-tree Sphinx is old and broken (and upgrade is blocked by py2 consumers).
1. yes 2. still reading
2. yes
This is published already at: https://projects.gentoo.org/qa/policy-guide/ and has a new nice theme. If there's anything else to be done, we'll file a separate bug.
