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 <ler...@redhat.com> Sent: Thursday, April 16, 2020 7:52 AM To: Sean Brogan <sean.bro...@microsoft.com> Cc: devel@edk2.groups.io; Ard Biesheuvel <ard.biesheu...@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&data=02%7C01%7Csean.brogan%40microsoft.com%7Cd94de877b9e74e06f08208d7e215bca4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637226455298322408&sdata=afDNhjdLt%2B9G4idYYGARh0RiTUnxCBx4fyBA5xT8k9Q%3D&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&data=02%7C01%7Csean.brogan%40microsoft.com%7Cd94de877b9e74e06f08208d7e215bca4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637226455298322408&sdata=nUtyttk3BdcGKyTepkUy0OnILT7%2FcBnHCMyt5eAO%2BG8%3D&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 -=-=-=-=-=-=-=-=-=-=-=- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#57562): https://edk2.groups.io/g/devel/message/57562 Mute This Topic: https://groups.io/mt/72880537/21656 Group Owner: devel+ow...@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com] -=-=-=-=-=-=-=-=-=-=-=-
