Re: [gentoo-dev] New QA Policy Guide

[Michał Górny]

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