[gentoo-dev] New QA Policy Guide

[gentoo-dev] New QA Policy Guide

[Michał Górny]

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

Hello,

In the light of the recent misunderstandings, I have started working
on an official Policy Guide [1].  The Guide is meant to provide
a focused list of officially approved QA policies, along with their
rationale and any other useful information.

This should supplement devmanual [2] with clear information on what is
enforceable policy, and what is merely a suggestion (or possibly
outdated information, which is a common problem for devmanual).

The current document contents were approved by the QA project.  However,
it is by no means complete.  Further existing policies (as well as new
policies) will be documented there as they are approved by QA team.

The sources are stored in proj/policy-guide.git [3].  If you wish to
submit your own changes, you can either use the 'Policy Guide' bugzilla
component [4] and/or GitHub mirror [5].

Enjoy!


[1] https://projects.gentoo.org/qa/policy-guide/
[2] https://devmanual.gentoo.org/
[3] https://gitweb.gentoo.org/proj/policy-guide.git/
[4] https://bugs.gentoo.org/enter_bug.cgi?product=Documentation&component=Policy+Guide
[5] https://github.com/gentoo/policy-guide

-- 
Best regards,
Michał Górny


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

Re: [gentoo-dev] New QA Policy Guide

[Ulrich Mueller]

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

>>>>> On Sun, 19 Jan 2020, Michał Górny wrote:

> The sources are stored in proj/policy-guide.git [3].  If you wish to
> submit your own changes, you can either use the 'Policy Guide' bugzilla
> component [4] and/or GitHub mirror [5].

Please, no github for official policies. We should have a permanent
paper trail for this kind of things, which isn't guaranteed if the
discussion would happen entirely on github.

Besides, by the Social Contract we cannot rely on a non-free service
for anything official.

Ulrich

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

Re: [gentoo-dev] New QA Policy Guide

[Rich Freeman]

On Sun, Jan 19, 2020 at 6:46 AM Ulrich Mueller <ulm@gentoo.org> wrote:
>
> >>>>> On Sun, 19 Jan 2020, Michał Górny wrote:
>
> > The sources are stored in proj/policy-guide.git [3].  If you wish to
> > submit your own changes, you can either use the 'Policy Guide' bugzilla
> > component [4] and/or GitHub mirror [5].
>
> Please, no github for official policies. We should have a permanent
> paper trail for this kind of things, which isn't guaranteed if the
> discussion would happen entirely on github.
>
> Besides, by the Social Contract we cannot rely on a non-free service
> for anything official.

The official sources aren't in github.  A bugzilla component is
available, so if github goes away there is no problem and we aren't
relying on it.

It looks like there is the optional ability to do work on github, just
as people can optionally talk about anything, anywhere.

If I have a chat with another package maintainer at a bar, and they
modify their ebuild and push that to the Gentoo repo on infra, and no
bug is ever opened, that is 100% within our current policy.  I don't
see how having that discussion on github instead of at the bar changes
things.

They're just offering an alternative place to get things done.
Anybody who wants to could just file a bug instead.

If we want to have an additional Gentoo policy that nobody is allowed
to discuss a Gentoo policy outside of the lists and bugzilla that
would of course create issues with stuff like github, and probably
non-logged IRC channels and private messages as well.  However, that
is not our current policy.  Plenty of council decisions happen with
much of the actual discussion not being recorded anywhere.  I'm not
sure you could reasonably operate in any other way, as people do need
the ability to talk things out without having to posture.

I feel like this discussion has already happened in the past though...

-- 
Rich

Re: [gentoo-dev] New QA Policy Guide

[Kent Fredric]

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

On Sun, 19 Jan 2020 07:08:30 -0500
Rich Freeman <rich0@gentoo.org> wrote:

> The official sources aren't in github.  A bugzilla component is
> available, so if github goes away there is no problem and we aren't
> relying on it.

If github goes away after bugs and PR's are filed on github, then that
historical context is lost, and may include the loss of open bugs and
open PRs, which all may still be relevant.

Many people consider that to be a bad thing.

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [gentoo-dev] New QA Policy Guide

[Rich Freeman]

On Sun, Jan 19, 2020 at 1:45 PM Kent Fredric <kentnl@gentoo.org> wrote:
>
> On Sun, 19 Jan 2020 07:08:30 -0500
> Rich Freeman <rich0@gentoo.org> wrote:
>
> > The official sources aren't in github.  A bugzilla component is
> > available, so if github goes away there is no problem and we aren't
> > relying on it.
>
> If github goes away after bugs and PR's are filed on github, then that
> historical context is lost, and may include the loss of open bugs and
> open PRs, which all may still be relevant.

Nothing of importance should be stored on github.

If you and I have a conversation at a bar, and as a result you decide
to make a commit without any useful comments, and then we both retire
from the project, just as much information is lost.

We don't require anybody to open a bug before making a commit today,
so why would we be concerned when non-required outside documentation
is stored in github?  That is more information than we already
require, so if it goes away nothing required by policy is lost.

If we made it a policy that all commits required some kind of peer
review in bugzilla, then of course we should do the same here.  Right
now we do not require that background for just about anything the
distro does be recorded anywhere.

If github's existence bothers you, then just pretend it doesn't exist
- stick it in your hosts file or block it at your router.  In theory
it shouldn't change your Gentoo experience at all.  :)

-- 
Rich

Re: [gentoo-dev] New QA Policy Guide

[Kent Fredric]

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

On Sun, 19 Jan 2020 13:54:33 -0500
Rich Freeman <rich0@gentoo.org> wrote:

> Nothing of importance should be stored on github.
> 
> If you and I have a conversation at a bar, and as a result you decide
> to make a commit without any useful comments, and then we both retire
> from the project, just as much information is lost.

Its not that I'm saying that this should be forbidden, only that there
is a tangible risk of lost of useful information.

Having a discussion at a bar, and you making a commit as a result is
one thing, but if I discovered a bug, and then only told you about it
at the bar, that would be possibly bad, because there's no guarantee
that the bug is communicated sufficient to ensure it gets addressed,
and you may go home at the end of the night and entirely forget the bug
existed, and people could continue to suffer it, and potentially
neglect to report it as well. ( End users are substantially less likely
to file bugs, IME )

When I mention bugs to people on IRC, I often follow up with "Would you
like me to file a bug?".

Often, the answer is "yes".

The crux of the matter being bugs that exist, and are communicated
outside the core bug tracker, weaken the assurance that it will be seen
and fixed, which amounts to a negative thing.

I wouldn't forbid such a thing, just make it clear that doing so is a
lower standard of quality, has risks, and should come with a level of
discouragement.



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [gentoo-dev] New QA Policy Guide

[Rich Freeman]

On Sun, Jan 19, 2020 at 2:32 PM Kent Fredric <kentnl@gentoo.org> wrote:
>
> Having a discussion at a bar, and you making a commit as a result is
> one thing, but if I discovered a bug, and then only told you about it
> at the bar, that would be possibly bad, because there's no guarantee
> that the bug is communicated sufficient to ensure it gets addressed,
> and you may go home at the end of the night and entirely forget the bug
> existed, and people could continue to suffer it, and potentially
> neglect to report it as well. ( End users are substantially less likely
> to file bugs, IME )
>
> When I mention bugs to people on IRC, I often follow up with "Would you
> like me to file a bug?".
>
> Often, the answer is "yes".
>
> The crux of the matter being bugs that exist, and are communicated
> outside the core bug tracker, weaken the assurance that it will be seen
> and fixed, which amounts to a negative thing.

Oh, I absolutely agree with this.

My point is that right now we have no policy that requires bugs to be
filed.  And hence stuff that happens on github really is no different
than your case of stuff happening in a bar.

I can't speak for the QA repo, but don't we have a bot that notices
open pull requests for the main repo mirror on github which are
missing bug references to post notices to this effect?  When this
started happening I think a lot of the concerns were reduced.

I mean, like was already mentioned, if there were a gitlab repo or
whatever being hosted a lot of this might become moot.  We're just not
there yet.

I'm not sure if the Foundation has considered approaching gitlab.com
about hosting.  Granted, that isn't their FOSS product, but I suspect
the repos could be exported and imported into the FOSS product as a
contingency.  I have it on good authority from somebody who works
there that their proprietary hosted product is identical to the FOSS
one aside from the proprietary modules, so as long as you avoid the
latter it should be the same thing.  If they're willing to donate or
offer cheaper hosting it might give us the benefits of the FOSS
repository while avoiding the hassles of hosting Ruby or whatever it
is written in.

-- 
Rich

Re: [gentoo-dev] New QA Policy Guide

[Thomas Deutschmann]

[-- Attachment #1.1: Type: text/plain, Size: 1151 bytes --]

On 2020-01-19 12:46, Ulrich Mueller wrote:
>>>>>> On Sun, 19 Jan 2020, Michał Górny wrote:
> 
>> The sources are stored in proj/policy-guide.git [3].  If you wish to
>> submit your own changes, you can either use the 'Policy Guide' bugzilla
>> component [4] and/or GitHub mirror [5].
> 
> Please, no github for official policies. We should have a permanent
> paper trail for this kind of things, which isn't guaranteed if the
> discussion would happen entirely on github.
> 
> Besides, by the Social Contract we cannot rely on a non-free service
> for anything official.

I would second that but this would also apply to devmanual.

And at some point it will also affect contribution to Gentoo repository
at Github itself: Sure, eclass changes require ML review but sometimes
comments contain valuable information especially for the future when
someone wants to understand why an ebuild was changed that way.

That's why Debian created https://salsa.debian.org/, Fedora has
https://src.fedoraproject.org/ ...


-- 
Regards,
Thomas Deutschmann / Gentoo Linux Developer
C4DD 695F A713 8F24 2AA1 5638 5849 7EE5 1D5D 74A5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

Re: [gentoo-dev] New QA Policy Guide

[Michał Górny]

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

On Sun, 2020-01-19 at 18:50 +0100, Thomas Deutschmann wrote:
> On 2020-01-19 12:46, Ulrich Mueller wrote:
> > > > > > > On Sun, 19 Jan 2020, Michał Górny wrote:
> > > The sources are stored in proj/policy-guide.git [3].  If you wish to
> > > submit your own changes, you can either use the 'Policy Guide' bugzilla
> > > component [4] and/or GitHub mirror [5].
> > 
> > Please, no github for official policies. We should have a permanent
> > paper trail for this kind of things, which isn't guaranteed if the
> > discussion would happen entirely on github.
> > 
> > Besides, by the Social Contract we cannot rely on a non-free service
> > for anything official.
> 
> I would second that but this would also apply to devmanual.
> 
> And at some point it will also affect contribution to Gentoo repository
> at Github itself: Sure, eclass changes require ML review but sometimes
> comments contain valuable information especially for the future when
> someone wants to understand why an ebuild was changed that way.

Valuable information belongs in comments in the ebuild or in the commit
message.

> That's why Debian created https://salsa.debian.org/, Fedora has
> https://src.fedoraproject.org/ ...

...and Gentoo developers are doing what they do best -- talking big.

-- 
Best regards,
Michał Górny


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

Re: [gentoo-dev] New QA Policy Guide

[Haelwenn (lanodan) Monnier]

Thanks a lot for this policy guide, finally there is a good documentation 
on them. 

I found one issue with it though, on pages like other-metadata.html and 
keywords.html the links are too large and squish the dt elements, one way 
I found to fix it is by adding `word-break: break-all` to a.reference but 
maybe it should use a selector closer to the root.

Re: [gentoo-dev] New QA Policy Guide

[Michał Górny]

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

On Sun, 2020-01-19 at 19:44 +0100, Haelwenn (lanodan) Monnier wrote:
> Thanks a lot for this policy guide, finally there is a good documentation 
> on them. 
> 
> I found one issue with it though, on pages like other-metadata.html and 
> keywords.html the links are too large and squish the dt elements, one way 
> I found to fix it is by adding `word-break: break-all` to a.reference but 
> maybe it should use a selector closer to the root.
> 

Please report bugs at [1].

[1] https://github.com/mmagorsc/tyrian_sphinx_theme

-- 
Best regards,
Michał Górny


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

Re: [gentoo-dev] New QA Policy Guide

[Michał Górny]

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

On Sun, 2020-01-19 at 19:44 +0100, Haelwenn (lanodan) Monnier wrote:
> Thanks a lot for this policy guide, finally there is a good documentation 
> on them. 
> 
> I found one issue with it though, on pages like other-metadata.html and 
> keywords.html the links are too large and squish the dt elements, one way 
> I found to fix it is by adding `word-break: break-all` to a.reference but 
> maybe it should use a selector closer to the root.
> 

Ok, I am sorry.  I've sent this mail with the conviction that new
version was deployed but I've been informed that it didn't.  I've
manually updated the site now, and it should show the new theme after
refresh.

-- 
Best regards,
Michał Górny


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

Re: [gentoo-dev] New QA Policy Guide

[Kent Fredric]

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

On Sun, 19 Jan 2020 12:31:52 +0100
Michał Górny <mgorny@gentoo.org> wrote:

> Enjoy!

Many thanks for making this happen.

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [gentoo-dev] New QA Policy Guide

[Robin H. Johnson]

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

On Sun, Jan 19, 2020 at 12:31:52PM +0100, Michał Górny wrote:
> Hello,
> 
> In the light of the recent misunderstandings, I have started working
> on an official Policy Guide [1].  The Guide is meant to provide
> a focused list of officially approved QA policies, along with their
> rationale and any other useful information.
> 
> This should supplement devmanual [2] with clear information on what is
> enforceable policy, and what is merely a suggestion (or possibly
> outdated information, which is a common problem for devmanual).
Thank you for this this!

I have some requests for improvement & content.

1. Stable identifiers for policy:
Assign ID numbers or stable identifying slugs to each policy and use
them for referencing from all tooling in future. Also makes searching
MUCH easier.

The ID variant might be 'GPNNNNN' (string prefix, followed by numeric
value)

The slug variant (modelled after Rubocop) might be
"Ebuild:CodingStyle"

My personal preference would be the ID variant, after seeing Rubocop
have to rename identifying slugs slowly & painfully over many years;
however the slug variant is MUCH better for usability 

2. Usability/viewing:
2.1. DT-squashed:
Please fix the CSS rendering of the <dt>. My chrome window is 1198 x
1870 (screen is portrait version 1920x1200).
Screenshot:
https://dev.gentoo.org/~robbat2/.private/20200119-policy-guide-render-window.png

2.2. Whitespace:
The left column has a LOT of wasted whitespace.

2.3 Navigation:
Please add next/previous links on the top AND bottom of each page.

2.4. Search results:
Many two-letter search terms return nothing, "QA", "QT"

3.  Content requests:
3.1.
Cover policy around ELF binary dependency verification (this related to
the ebuild maintainer quiz question "How can you verify an ebuild has
correct run time dependencies (RDEPEND) for all installed binaries?"

3.2. 
Cover policy around making sure that ALL licenses around installed
data being listed in the LICENSE variable, which is becoming
increasingly important for Rust & Go where the output binaries are
usually static, and many licenses might be included via dependencies
on the codebase.

-- 
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

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

Re: [gentoo-dev] New QA Policy Guide

[Michał Górny]

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

On Sun, 2020-01-19 at 19:34 +0000, Robin H. Johnson wrote:
> On Sun, Jan 19, 2020 at 12:31:52PM +0100, Michał Górny wrote:
> > Hello,
> > 
> > In the light of the recent misunderstandings, I have started working
> > on an official Policy Guide [1].  The Guide is meant to provide
> > a focused list of officially approved QA policies, along with their
> > rationale and any other useful information.
> > 
> > This should supplement devmanual [2] with clear information on what is
> > enforceable policy, and what is merely a suggestion (or possibly
> > outdated information, which is a common problem for devmanual).
> Thank you for this this!
> 
> I have some requests for improvement & content.
> 
> 1. Stable identifiers for policy:
> Assign ID numbers or stable identifying slugs to each policy and use
> them for referencing from all tooling in future. Also makes searching
> MUCH easier.
> 
> The ID variant might be 'GPNNNNN' (string prefix, followed by numeric
> value)
> 
> The slug variant (modelled after Rubocop) might be
> "Ebuild:CodingStyle"
> 
> My personal preference would be the ID variant, after seeing Rubocop
> have to rename identifying slugs slowly & painfully over many years;
> however the slug variant is MUCH better for usability 

I was wondering about this.  However, wouldn't permalinks be good
enough?  Each section has its own anchor, and it makes them immediately
useful for seeing the policy in question without having to resort to
searching.

> 2. Usability/viewing:
> 2.1. DT-squashed:
> Please fix the CSS rendering of the <dt>. My chrome window is 1198 x
> 1870 (screen is portrait version 1920x1200).
> Screenshot:
> https://dev.gentoo.org/~robbat2/.private/20200119-policy-guide-render-window.png
> 
> 2.2. Whitespace:
> The left column has a LOT of wasted whitespace.
> 
> 2.3 Navigation:
> Please add next/previous links on the top AND bottom of each page.

Please file theme-related bugs at:
https://github.com/mmagorsc/tyrian_sphinx_theme

> 
> 2.4. Search results:
> Many two-letter search terms return nothing, "QA", "QT"

I suspect this is Sphinx's limitation and I'm not qualified to deal with
it.  I'd suggest using index + in-page search.  That said, I'm open to
pull requests / patches to improve index.

> 3.  Content requests:
> 3.1.
> Cover policy around ELF binary dependency verification (this related to
> the ebuild maintainer quiz question "How can you verify an ebuild has
> correct run time dependencies (RDEPEND) for all installed binaries?"
> 
> 3.2. 
> Cover policy around making sure that ALL licenses around installed
> data being listed in the LICENSE variable, which is becoming
> increasingly important for Rust & Go where the output binaries are
> usually static, and many licenses might be included via dependencies
> on the codebase.

Could you file bugs for that (on Bugzilla)?

-- 
Best regards,
Michał Górny


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

Re: [gentoo-dev] New QA Policy Guide

[Michał Górny]

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

On Sun, 2020-01-19 at 19:34 +0000, Robin H. Johnson wrote:
> On Sun, Jan 19, 2020 at 12:31:52PM +0100, Michał Górny wrote:
> > Hello,
> > 
> > In the light of the recent misunderstandings, I have started working
> > on an official Policy Guide [1].  The Guide is meant to provide
> > a focused list of officially approved QA policies, along with their
> > rationale and any other useful information.
> > 
> > This should supplement devmanual [2] with clear information on what is
> > enforceable policy, and what is merely a suggestion (or possibly
> > outdated information, which is a common problem for devmanual).
> Thank you for this this!
> 
> I have some requests for improvement & content.
> 
> 1. Stable identifiers for policy:
> Assign ID numbers or stable identifying slugs to each policy and use
> them for referencing from all tooling in future. Also makes searching
> MUCH easier.
> 
> The ID variant might be 'GPNNNNN' (string prefix, followed by numeric
> value)
> 
> The slug variant (modelled after Rubocop) might be
> "Ebuild:CodingStyle"
> 
> My personal preference would be the ID variant, after seeing Rubocop
> have to rename identifying slugs slowly & painfully over many years;
> however the slug variant is MUCH better for usability 
> 
> 2. Usability/viewing:
> 2.1. DT-squashed:
> Please fix the CSS rendering of the <dt>. My chrome window is 1198 x
> 1870 (screen is portrait version 1920x1200).
> Screenshot:
> https://dev.gentoo.org/~robbat2/.private/20200119-policy-guide-render-window.png
> 
> 2.2. Whitespace:
> The left column has a LOT of wasted whitespace.
> 
> 2.3 Navigation:
> Please add next/previous links on the top AND bottom of each page.
> 

Ok, I am sorry.  I've sent this mail with the conviction that new
version was deployed but I've been informed that it didn't.  I've
manually updated the site now, and it should show the new theme after
refresh.

-- 
Best regards,
Michał Górny


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 614 bytes --]

Re: [gentoo-dev] New QA Policy Guide

[William Hubbs]

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

On Sun, Jan 19, 2020 at 12:31:52PM +0100, Michał Górny wrote:
> Hello,
> 
> In the light of the recent misunderstandings, I have started working
> on an official Policy Guide [1].  The Guide is meant to provide
> a focused list of officially approved QA policies, along with their
> rationale and any other useful information.
> 
> This should supplement devmanual [2] with clear information on what is
> enforceable policy, and what is merely a suggestion (or possibly
> outdated information, which is a common problem for devmanual).
> 
> The current document contents were approved by the QA project.  However,
> it is by no means complete.  Further existing policies (as well as new
> policies) will be documented there as they are approved by QA team.

Why are we creating another guide instead of just consolidating
everything in the devmanual?

My understanding of things has been that the devmanual is the location
of official qa policies, but now we have devmanual, this new guide and

https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Policies


> 
> The sources are stored in proj/policy-guide.git [3].  If you wish to
> submit your own changes, you can either use the 'Policy Guide' bugzilla
> component [4] and/or GitHub mirror [5].

I also agree with ulm et al wrt any official discussion wrt changes
needing to happen on bugzilla.

Thanks,

William

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