Re: [EXTERNAL] Re: [PATCH v2 0/6] Edk2 Platform and Core CI for ArmVirtPkg, EmulatorPkg, and OvmfPkg

["Sean" <sean.brogan@microsoft.com>]

I was hoping that because it wasn't "HTML tag soup" that build status could be front and center in the package readme as I find that more in line with expectations on github based projects.   Nesting it deeper in the package just means less people find it when looking at your package.   But I could see a few ways to solve it so I am looking for feedback and alignment before doing anything else. 

Option 1.

1. Add the Platform CI build status for the three platforms to the Edk2 repo readme since these are platforms in edk2 this makes sense and brings the most visibility to their status and the existence of the builds. 
2. Convert edk2 repo readme to RST so it avoids "HTML tag soup"
3. Move the remaining part of the OvmfPkg/Readme.rst file into OvmfPkg/PlatformCI/Readme.md  (I prefer MD when not doing large tables of links as it is easier to write and slightly easier to read as plain text).   
4. Do step 3 for ArmVirtPkg and EmulatorPkg too

Option 2.
1. Leave the ReadMe.rst at the root of each package but only include the build status table and add a link to the PlatformCi/ReadMe.md
2. Move the Pytool and Platform CI focused readme contents to PlatformCI/ReadMe.md

Option 3.

Something else.

Finally does anyone have a strong preference for ReadMe vs README vs readme vs Readme vs ReAdMe?  I see a mix of these in the edk2 code tree.   


Thanks
Sean







-----Original Message-----
From: Laszlo Ersek <lersek@redhat.com> 
Sent: Tuesday, April 21, 2020 7:18 AM
To: michael.kubacki@outlook.com; devel@edk2.groups.io
Cc: Andrew Fish <afish@apple.com>; Ard Biesheuvel <ard.biesheuvel@arm.com>; Bret Barkelew <Bret.Barkelew@microsoft.com>; Jordan Justen <jordan.l.justen@intel.com>; Leif Lindholm <leif@nuviainc.com>; Liming Gao <liming.gao@intel.com>; Kinney, Michael D <michael.d.kinney@intel.com>; Ray Ni <ray.ni@intel.com>; Sean Brogan <sean.brogan@microsoft.com>
Subject: [EXTERNAL] Re: [PATCH v2 0/6] Edk2 Platform and Core CI for ArmVirtPkg, EmulatorPkg, and OvmfPkg

On 04/20/20 21:12, michael.kubacki@outlook.com wrote:

>  ArmVirtPkg/ReadMe.rst                                     | 139 ++++++++++
>  EmulatorPkg/README.rst                                    | 175 +++++++++++++
>  OvmfPkg/README.rst                                        | 211 +++++++++++++++

I made a mistake -- I apologize.

* In my email here (two links to the same message):

    https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fmid.mail-archive.com%2F061ab841-33fb-b46f-a9e7-1b5ce0d2e2f4%40redhat.com&amp;data=02%7C01%7Csean.brogan%40microsoft.com%7C4ceccc8b356a4ccb1c0908d7e5fed61c%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637230754994306472&amp;sdata=8O9sO1da5nWLTieoA%2FH%2BOPIonp1rf3L07lQ3L4p9Ybg%3D&amp;reserved=0
    https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fedk2.groups.io%2Fg%2Fdevel%2Fmessage%2F57468&amp;data=02%7C01%7Csean.brogan%40microsoft.com%7C4ceccc8b356a4ccb1c0908d7e5fed61c%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637230754994306472&amp;sdata=U5N9NtRGiWf58I3F2NMcEe0vypkZuFlsCPQNnRjDCR8%3D&amp;reserved=0

  I gladly accepted the option offered by Sean that we put the
  CI-specific README files (for at least OvmfPkg and ArmVirtPkg) under
  the PlatformCI subdirectory. Quote:

On 04/16/20 16:51, Laszlo Ersek wrote:
> On 04/15/20 22:38, sean.brogan via [] wrote:
>> 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!

  Back then, the format for the readme was assumed MD, but that wasn't
  the main topic -- the main topic was the directory layout.

* Then, when the MD vs. RST format question came up, I checked the RST
  format (the *contents*), and I was happy with it. My email (two links
  again):

    https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fmid.mail-archive.com%2F1be6a25d-06e2-4109-8acf-0fe82d150af4%40redhat.com&amp;data=02%7C01%7Csean.brogan%40microsoft.com%7C4ceccc8b356a4ccb1c0908d7e5fed61c%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637230754994306472&amp;sdata=UMNbHUQw6s0AbwXUQmQ2QDMRjSJjbQg9bouW9AbffAU%3D&amp;reserved=0
    https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fedk2.groups.io%2Fg%2Fdevel%2Fmessage%2F57611&amp;data=02%7C01%7Csean.brogan%40microsoft.com%7C4ceccc8b356a4ccb1c0908d7e5fed61c%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637230754994306472&amp;sdata=wvtrWaYQQjliFZmZWXjtIcKXockdV5j3RPNElXIJpcY%3D&amp;reserved=0

  *However*, unfortunately, when looking at the RST format improvements,
  I missed that Sean implemented the RST files directly in the package
  root directories; and *not* under the PlatformCI directory. I'm very
  sorry for missing that -- I assumed that the text files were under
  PlatformCI like I had requested / agreed earlier, and I didn't realize
  from the URLs that Sean pasted that this wasn't the case.


So, I have two observations / requests:

(1) The three RST file names are capitalized differently (two use ALL CAPS, one uses CamelCase), before the .rst suffix. Please stick with one style.

(2) I'd really like these RST text files to be moved under the respective PlatformCI directories. (My understanding is, from Sean's message quoted above, that this is possible, and github can display it well when the user browses the PlatformCI directory in a web browser.)

With those updates, for the OvmfPkg and ArmVirtPkg patches:

Acked-by: Laszlo Ersek <lersek@redhat.com>

Thanks!
Laszlo