From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from us-smtp-delivery-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.81]) by mx.groups.io with SMTP id smtpd.web12.8139.1587048729534118782 for ; Thu, 16 Apr 2020 07:52:09 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@redhat.com header.s=mimecast20190719 header.b=ehbKp1IZ; spf=pass (domain: redhat.com, ip: 207.211.31.81, mailfrom: lersek@redhat.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1587048728; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=5c1xFMVggM6Uv9i92Wo7V6WlGrrRGSZnmvTs73MYFjg=; b=ehbKp1IZsTbFautF955mABoI7cnhhc7Aflhc4c+9j5Y7cDpUujrpuLaHhDjjApty6IRqtU LgZELGNl0cjagwT3zKhcbWY7uHnjj1XP4E5Qt5FxC8rx7/4ZjcOnz9eEfzhkPxsT5qnBoU JhIShFZrZt+J1KMska/mVdnwtK/4+Os= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-347-03pDwMRYPBmHUoJtJs6acQ-1; Thu, 16 Apr 2020 10:52:01 -0400 X-MC-Unique: 03pDwMRYPBmHUoJtJs6acQ-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 4ACEF102CE14; Thu, 16 Apr 2020 14:52:00 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-114-225.ams2.redhat.com [10.36.114.225]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3C1B81001DD8; Thu, 16 Apr 2020 14:51:59 +0000 (UTC) Subject: Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI To: Sean References: <3e0cfe33-c972-9bdd-5db5-25c52a720823@redhat.com> <31845.1586983083124497540@groups.io> From: "Laszlo Ersek" Cc: devel@edk2.groups.io, Ard Biesheuvel Message-ID: <061ab841-33fb-b46f-a9e7-1b5ce0d2e2f4@redhat.com> Date: Thu, 16 Apr 2020 16:51:58 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.9.1 MIME-Version: 1.0 In-Reply-To: <31845.1586983083124497540@groups.io> X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Language: en-US Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit 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