Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI

Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI

[Sean]

Laszlo,

Regarding your comments about disliking the verbosity of the markdown table/html table for build status both in Core Ci and now these Platform CI readme files.  

As a learning experience I updated the OvmfPkg readme to use reStructuredText instead of markdown.  Not sure if I like RST but it does allow the links to not be in html and supports directives so you can push all that text to end of the file.  

Do you like this enough that I should rework all three readmes and we should discuss if RST should be used instead of MD for the edk2 project? 

RST version: https://github.com/spbrogan/edk2/blob/PlatformAndCoreCIForOvmfArmVirtEmulatorPackages_v8/OvmfPkg/README.rst 
MD version: https://github.com/spbrogan/edk2/blob/PlatformAndCoreCIForOvmfArmVirtEmulatorPackages_v7/OvmfPkg/README-pytools.md

This is really the last remaining issue for the PlatformCI patchset.

Thanks
Sean



-----Original Message-----
From: Laszlo Ersek <lersek@redhat.com> 
Sent: Thursday, April 16, 2020 7:52 AM
To: Sean Brogan <sean.brogan@microsoft.com>
Cc: devel@edk2.groups.io; Ard Biesheuvel <ard.biesheuvel@linaro.org>
Subject: [EXTERNAL] Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI

On 04/15/20 22:38, sean.brogan via [] wrote:
> On Wed, Apr 15, 2020 at 10:18 AM, Laszlo Ersek wrote:
>
>>
>> ArmVirtPkg/ArmVirtPkg.ci.yaml
>> ArmVirtPkg/PlatformCI/Ubuntu-GCC5.yml
>> ArmVirtPkg/PlatformCI/PlatformBuild.py
>> ArmVirtPkg/PlatformCI/README-pytools.md
>> ArmVirtPkg/PlatformCI/iasl_ext_dep.yaml
>
> I am ok with the above except one thought on the readme.  One nice 
> thing about the markdown readme files are the badge shows up in github 
> when you view the package.  This is a quick and easy way to see the 
> current status.

I agree this is very useful.

What I dislike is that, when I open "Readme.md" (e.g. in the project
root) in a normal terminal, I'm greeted by a HTML tag soup under the heading "# Build Status".

Markdown is supposed to be readable as plain text. Embedding the page-ful of build status HTML in "Readme.md" defeats that purpose.
github should either consume a different file (too) for displaying status badges, or else the "Readme.md" file should reference the HTML snippet in question with some kind of link or directive, rather than directly containing it.

Perhaps github already offers this feature -- that would be awesome. I would be happy with the following variant, for example:

  ArmVirtPkg/ArmVirtPkg.ci.yaml
  ArmVirtPkg/PlatformCI/PlatformBuild.py
  ArmVirtPkg/PlatformCI/Ubuntu-GCC5.yml
  ArmVirtPkg/PlatformCI/iasl_ext_dep.yaml
  ArmVirtPkg/README-ci.md
  ArmVirtPkg/README.md

"README.md" would contain the package description that read nice in a terminal too. Then, "README.md" would either (somehow?) include "README-ci.md" by reference, or else github would render both "README-ci.md" and "README.md".

>
> * Ovmf has a pretty stale readme

Hm, I'd say "somewhat" stale. We do keep it up-to-date with "very important" stuff.

My excuse for not polishing it more -- which I honestly do believe is a
*valid* excuse -- is that users have shown repeatedly that they don't read the README at all. I've explained basic stuff like "how to capture OVMF's debug log" umpteen times on the list, despite it being spelled out in the README. The fact is that effort put towards careful documentation is almost entirely lost effort -- this was also clearly proved by the (non-)reaction that I got to my OVMF white paper that I wrote a few years back (~60 A4 pages, if I recall correctly).

Documentation is just not *worth* polishing, considering the user base as a whole. I for one go to the available documentation *before* starting to use new software, or when questions pop up, but it seems like I belong to a vanishingly small camp with that. People just flock to social media (or, in the least wrong case: they come to this mailing list), and ask questions they could already find the answers to in existent documentation.

This is a  bitter realization for me, especially having written relatively substantial articles for the edk2 wiki:

  https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Ftianocore%2Ftianocore.github.io%2Fwiki%2FLaszlo%27s-unkempt-git-guide-for-edk2-contributors-and-maintainers&amp;data=02%7C01%7Csean.brogan%40microsoft.com%7Cd94de877b9e74e06f08208d7e215bca4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637226455298322408&amp;sdata=afDNhjdLt%2B9G4idYYGARh0RiTUnxCBx4fyBA5xT8k9Q%3D&amp;reserved=0
  https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Ftianocore%2Ftianocore.github.io%2Fwiki%2FTesting-SMM-with-QEMU%2C-KVM-and-libvirt&amp;data=02%7C01%7Csean.brogan%40microsoft.com%7Cd94de877b9e74e06f08208d7e215bca4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637226455298322408&amp;sdata=nUtyttk3BdcGKyTepkUy0OnILT7%2FcBnHCMyt5eAO%2BG8%3D&amp;reserved=0

but it is what I now believe.

> and does not take advantage of markdown.

Correct. That's not intentional; I think the README just predates the usefulness of markdown (i.e. it predates moving the project to github.com). IIRC.

> We could convert it to MD, clean up, and then merge in the content 
> from the pytools.md.  I would need help or a package maintainer to do 
> the cleanup of the readme to make sure it contained the content you 
> desired.

So my problem with this is two-fold. First, regarding just the markdown conversion, I agree it would be nice, but I don't wish to sink any work into it (see my opinion above, about polishing documentation). If someone wanted to spend time on just a structural conversion to markdown (not modifying content), I'd be OK to review that.

Second, merging (i.e., flattening) the tag soup from "README-pytools.md"
into the main package "Readme.md" is something that I'm opposed to, as it interferes with consuming the readme from a plain terminal or text editor.

> * ArmVirtPkg doesn't have a readme and this is definitely a barrier to 
> entry for the package.  I would suggest creating one and then merging 
> in the content from the pytools.md.

Creating a readme in MD format: would be nice if someone contributed that ("patches welcome" :) ).

*Merging* the HTML tag soup: please let's not do that. (I'm totally fine if it is introduced in a separate, appropriately named or located file.)

> * EmulatorPkg has one.  I would just suggest a merge but i am yet to 
> get any feedback from those maintainers.
>
> If that isn't desirable i would at least suggest we change the title 
> to just ReadMe.md so that GitHub shows it by default when the 
> PaltformCI folder is viewed form the web or in editor like vscode.

This sounds 100% viable and great to me. I didn't expect this could work! (I'm generally unaware of the readme filename patterns, and locations, that github.com recognizes; sorry about that.) Having an "unadorned" ReadMe.md file under PlatformCI is just perfect.

So if I understand correctly, we could choose:

  ArmVirtPkg/ArmVirtPkg.ci.yaml
  ArmVirtPkg/PlatformCI/PlatformBuild.py
  ArmVirtPkg/PlatformCI/ReadMe.md
  ArmVirtPkg/PlatformCI/Ubuntu-GCC5.yml
  ArmVirtPkg/PlatformCI/iasl_ext_dep.yaml

Do I understand right?

Because, I'd find this great!

Thank you!
Laszlo

Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI

[Ard Biesheuvel]

On 4/19/20 10:29 AM, Sean via groups.io wrote:
> Laszlo,
> 
> Regarding your comments about disliking the verbosity of the markdown table/html table for build status both in Core Ci and now these Platform CI readme files.
> 
> As a learning experience I updated the OvmfPkg readme to use reStructuredText instead of markdown.  Not sure if I like RST but it does allow the links to not be in html and supports directives so you can push all that text to end of the file.
> 
> Do you like this enough that I should rework all three readmes and we should discuss if RST should be used instead of MD for the edk2 project?
> 
> RST version: https://github.com/spbrogan/edk2/blob/PlatformAndCoreCIForOvmfArmVirtEmulatorPackages_v8/OvmfPkg/README.rst
> MD version: https://github.com/spbrogan/edk2/blob/PlatformAndCoreCIForOvmfArmVirtEmulatorPackages_v7/OvmfPkg/README-pytools.md
> 

I think the rendered RST looks really good, and is perfectly usable as 
plaintext too. AFAICT, we are not losing out on anything the v7 version 
provided, right? If not, I am in favor of going with RST in this case, 
which I suppose implies that I am in favor of permitting it in EDK2 for 
purposes such as this one.

That does not necessarily imply that all markdown should be replaced 
with RST. I'm perfectly happy letting them co-exist, and I don't have an 
opinion on whether one should be recommended over the other, or which 
that should have to be.

> This is really the last remaining issue for the PlatformCI patchset.
> 

Agreed. This is converging really nicely.

-- 
Ard.

Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI

[Laszlo Ersek]

On 04/19/20 11:35, Ard Biesheuvel wrote:
> On 4/19/20 10:29 AM, Sean via groups.io wrote:
>> Laszlo,
>>
>> Regarding your comments about disliking the verbosity of the markdown
>> table/html table for build status both in Core Ci and now these
>> Platform CI readme files.
>>
>> As a learning experience I updated the OvmfPkg readme to use
>> reStructuredText instead of markdown.  Not sure if I like RST but it
>> does allow the links to not be in html and supports directives so you
>> can push all that text to end of the file.
>>
>> Do you like this enough that I should rework all three readmes and we
>> should discuss if RST should be used instead of MD for the edk2 project?
>>
>> RST version:
>> https://github.com/spbrogan/edk2/blob/PlatformAndCoreCIForOvmfArmVirtEmulatorPackages_v8/OvmfPkg/README.rst
>>
>> MD version:
>> https://github.com/spbrogan/edk2/blob/PlatformAndCoreCIForOvmfArmVirtEmulatorPackages_v7/OvmfPkg/README-pytools.md
>>
>>
> 
> I think the rendered RST looks really good, and is perfectly usable as
> plaintext too. AFAICT, we are not losing out on anything the v7 version
> provided, right? If not, I am in favor of going with RST in this case,
> which I suppose implies that I am in favor of permitting it in EDK2 for
> purposes such as this one.
> 
> That does not necessarily imply that all markdown should be replaced
> with RST. I'm perfectly happy letting them co-exist, and I don't have an
> opinion on whether one should be recommended over the other, or which
> that should have to be.
> 
>> This is really the last remaining issue for the PlatformCI patchset.
>>
> 
> Agreed. This is converging really nicely.
> 

Agreed 100% on all counts.

Thanks
Laszlo

Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI

[Rebecca Cran]

> -----Original Message-----
> From: Laszlo Ersek <lersek@redhat.com>
> Sent: Thursday, April 16, 2020 7:52 AM
> To: Sean Brogan <sean.brogan@microsoft.com>
> Cc: devel@edk2.groups.io; Ard Biesheuvel <ard.biesheuvel@linaro.org>
> Subject: [EXTERNAL] Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI
>
>
> My excuse for not polishing it more -- which I honestly do believe is a
> *valid* excuse -- is that users have shown repeatedly that they don't read the README at all. I've explained basic stuff like "how to capture OVMF's debug log" umpteen times on the list, despite it being spelled out in the README. The fact is that effort put towards careful documentation is almost entirely lost effort -- this was also clearly proved by the (non-)reaction that I got to my OVMF white paper that I wrote a few years back (~60 A4 pages, if I recall correctly).
>
> Documentation is just not *worth* polishing, considering the user base as a whole. I for one go to the available documentation *before* starting to use new software, or when questions pop up, but it seems like I belong to a vanishingly small camp with that. People just flock to social media (or, in the least wrong case: they come to this mailing list), and ask questions they could already find the answers to in existent documentation.
>
> This is a  bitter realization for me, especially having written relatively substantial articles for the edk2 wiki:
>
>    https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Ftianocore%2Ftianocore.github.io%2Fwiki%2FLaszlo%27s-unkempt-git-guide-for-edk2-contributors-and-maintainers&amp;data=02%7C01%7Csean.brogan%40microsoft.com%7Cd94de877b9e74e06f08208d7e215bca4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637226455298322408&amp;sdata=afDNhjdLt%2B9G4idYYGARh0RiTUnxCBx4fyBA5xT8k9Q%3D&amp;reserved=0
>    https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Ftianocore%2Ftianocore.github.io%2Fwiki%2FTesting-SMM-with-QEMU%2C-KVM-and-libvirt&amp;data=02%7C01%7Csean.brogan%40microsoft.com%7Cd94de877b9e74e06f08208d7e215bca4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637226455298322408&amp;sdata=nUtyttk3BdcGKyTepkUy0OnILT7%2FcBnHCMyt5eAO%2BG8%3D&amp;reserved=0
>
> but it is what I now believe.

Where are those pages linked from (i.e. how would people find them)? The 
Github wiki just confuses me: I don't see how it's useful for a project 
as large/complex as TianoCore.

Compare it to https://wiki.freebsd.org/, where there's a large table of 
contents right on the front page.  And then clicking on 'UEFI', you go 
to https://wiki.freebsd.org/UEFI where there's another table of contents 
- and has the breadcrumb navigation. It feels much easier to use to me 
at least.


And having looked through the OVMF README file in the past, I recall it 
being pretty difficult to find information in. It's a little long, and 
with it all being plain text it's not very easy to navigate.


-- 

Rebecca Cran

Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI

[Laszlo Ersek]

On 04/19/20 22:56, Rebecca Cran wrote:

> Where are those pages linked from (i.e. how would people find them)?

I've used the following three methods to find content in the wiki:

(1) web search

(2) if you open <https://github.com/tianocore/tianocore.github.io/wiki>
and click on the "Pages" box to the right, you get a small search field.

(3) grep a local clone of the wiki.

Not implying that these are convenient or efficient.

Thanks
Laszlo

Re: [EXTERNAL] Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI

[Bret Barkelew]

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

Reviewed-by: Bret Barkelew <bret.barkelew@microsoft.com>

- Bret

________________________________
From: devel@edk2.groups.io <devel@edk2.groups.io> on behalf of Laszlo Ersek via groups.io <lersek=redhat.com@groups.io>
Sent: Monday, April 20, 2020 4:08:53 AM
To: Rebecca Cran <rebecca@bsdio.com>; devel@edk2.groups.io <devel@edk2.groups.io>; Sean Brogan <sean.brogan@microsoft.com>
Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>; Kinney, Michael D <michael.d.kinney@intel.com>
Subject: [EXTERNAL] Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI

On 04/19/20 22:56, Rebecca Cran wrote:

> Where are those pages linked from (i.e. how would people find them)?

I've used the following three methods to find content in the wiki:

(1) web search

(2) if you open <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Ftianocore%2Ftianocore.github.io%2Fwiki&amp;data=02%7C01%7Cbret.barkelew%40microsoft.com%7C32def7f7f4f0408ce52908d7e51b3ca9%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637229777459482694&amp;sdata=%2BEw9TO%2F3VQATva2nbPNRMZDq7I3fBHx9YqOJvGIpX7k%3D&amp;reserved=0>
and click on the "Pages" box to the right, you get a small search field.

(3) grep a local clone of the wiki.

Not implying that these are convenient or efficient.

Thanks
Laszlo





[-- Attachment #2: Type: text/html, Size: 3502 bytes --]