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

Thu Apr 16 14:51:58 UTC 2020

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://github.com/tianocore/tianocore.github.io/wiki/Laszlo's-unkempt-git-guide-for-edk2-contributors-and-maintainers
  https://github.com/tianocore/tianocore.github.io/wiki/Testing-SMM-with-QEMU,-KVM-and-libvirt

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 (#57468): https://edk2.groups.io/g/devel/message/57468
Mute This Topic: https://groups.io/mt/72880537/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub  [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-