Re: [gentoo-dev] New QA Policy Guide
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 signature.asc Description: Digital signature
Re: [gentoo-dev] New QA Policy Guide
On Sun, 2020-01-19 at 19:34 +, 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 'GPN' (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 . 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 signature.asc Description: This is a digitally signed message part
Re: [gentoo-dev] New QA Policy Guide
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 signature.asc Description: This is a digitally signed message part
Re: [gentoo-dev] New QA Policy Guide
On Sun, Jan 19, 2020 at 2:32 PM Kent Fredric 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
On Sun, 2020-01-19 at 19:34 +, 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 'GPN' (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 . 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 signature.asc Description: This is a digitally signed message part
Re: [gentoo-dev] New QA Policy Guide
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 'GPN' (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 . 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 : robb...@gentoo.org GnuPG FP : 11ACBA4F 4778E3F6 E4EDF38E B27B944E 34884E85 GnuPG FP : 7D0B3CEB E9B85B1F 825BCECF EE05E6F6 A48F6136 signature.asc Description: PGP signature
Re: [gentoo-dev] New QA Policy Guide
On Sun, 19 Jan 2020 13:54:33 -0500 Rich Freeman 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. pgp5dvxl_ePUz.pgp Description: OpenPGP digital signature
Re: [gentoo-dev] New QA Policy Guide
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 signature.asc Description: This is a digitally signed message part
Re: [gentoo-dev] New QA Policy Guide
On Sun, Jan 19, 2020 at 1:45 PM Kent Fredric wrote: > > On Sun, 19 Jan 2020 07:08:30 -0500 > Rich Freeman 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
On Sun, 19 Jan 2020 12:31:52 +0100 Michał Górny wrote: > Enjoy! Many thanks for making this happen. pgpkU6bOR1NU6.pgp Description: OpenPGP digital signature
Re: [gentoo-dev] New QA Policy Guide
On Sun, 19 Jan 2020 07:08:30 -0500 Rich Freeman 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. pgpRfe3TY4eJv.pgp Description: OpenPGP digital signature
Re: [gentoo-dev] New QA Policy Guide
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
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 signature.asc Description: This is a digitally signed message part
Re: [gentoo-dev] New QA Policy Guide
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 signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] New QA Policy Guide
On Sun, Jan 19, 2020 at 6:46 AM 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. 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
> 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 signature.asc Description: PGP signature
