Re: [edk2-devel] [PATCH v4 0/9] support CPU hot-unplug

["Laszlo Ersek" <lersek@redhat.com>]

On 01/21/21 20:11, Ankur Arora wrote:
> On 2021-01-21 4:29 a.m., Laszlo Ersek wrote:

>> For catching such issues early on, please run "PatchCheck.py" before
>> posting, e.g. as in:
>>
>> $ python3 BaseTools/Scripts/PatchCheck.py master..topic_branch
>>
>> (In the present case, PatchCheck reports lots of "not CRLF" errors.)
>>
> 
> PatchCheck.py is great. Thanks.
> 
>>
>> An even better idea is to push your topic branch (which you're about to
>> post to the list) to your edk2 fork on github.com, and then submit a
>> pull request against the "tianocore/edk2" project. The pull request will
>> be auto-closed in the end (it will never be merged), but the goal is to
>> trigger a CI run on the patch set, and to give you the error messages if
>> any. PatchCheck runs as a part of CI, too.
>>
>> (github.com PRs are used for actual merging by edk2 maintainers, but for
>> that, they set the "push" label on the subject PRs, and the "push" label
>> is restricted to maintainers.)
>>
>> I apologize about the extra delay. Would you be OK posting v5?
> 
> Sure.

Thanks for your understanding, I'm relieved.

> Just a side question which I should have asked you earlier: are
> the coding standards listed somewhere?

Yes, see "C Coding Standards" at
<https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Documentation#specifications>.

Although...

> I had looked for answers to similar questions but the "TianoCore C style
> guide" doesn't mention either PatchCheck.py or rules around CRLF.

... you may have found exactly that, already. Unfortunately, like all
documentation in the world, this document is somewhat out of date.

There is also a tool, called ECC, that contains a builtin C language
parser, that enforces various style requirements. It's built into the CI
system and runs on github -- however, we have it disabled for OVMF, in
commit ef3e73c6a0c0 ("OvmfPkg: Disable EccCheck CI until EccCheck issues
are fixed", 2020-12-14). There are two reasons for that:

- Some stuff that ECC enforces is just overzealous -- in some cases, we
relax the coding style under OvmfPkg specifically, but ECC cannot easily
be configured to tolerate those relaxations (for example, you cannot
configure it to ignore a particular error code *regardless* of where it
occurs under OvmfPkg).

- In some cases, ECC rejects C language constructs that are both valid
and conformant to the coding style (i.e., ECC has its own bugs).


So we usually "teach" these quirks to contributors during review. It's
quite a lot of investment, which is part of why we hope that
contributors stick around.


An alternative is this: in your topic branch that you intend to post to
edk2-devel, include an *extra* patch (not to be posted to the list) that
*reverts* commit ef3e73c6a0c0. And submit a github.com PR with this
variant of your topic branch. As a result, ECC will be unleashed on (the
end-stage of) your patch series. If you fix all of the ECC issues, then
reviewers should make next to zero *style* complaints -- on the other
hand, you could be updating code that ECC complains about *incorrectly*
(due to an ECC bug, or because the subject style rule is something we
deem superfluous, or at least "possible to bend", under OvmfPkg).

So perhaps try to investigate this latter avenue, and see if you are
willing to deal with what ECC throws at you. :)

> Thanks for the comments and my apologies for making you review all of
> these non-substantive changes.

It's a standard part of reviewing the first few contributions of a new
community member; it's too bad we don't have better stuff in place. We
do have docs but they are slightly outdated, and we do have ECC but with
warts.

We also have recommendations (not official requirements!) on setting up
git, as a part of
<https://github.com/tianocore/tianocore.github.io/wiki/Laszlo's-unkempt-git-guide-for-edk2-contributors-and-maintainers>
-- which is likely out of date somewhat --; the

  BaseTools/Scripts/SetupGit.py

utility automates more or less the same settings.

We also have

  BaseTools/Scripts/GetMaintainer.py

which lets you determine the Cc:'s you should put in each commit message...

And when you dump all this *process* on a new contributor, they run away
screaming -- kind of justifiedly. :/

Thanks
Laszlo