Re: [edk2-devel] more development process failure [was: UefiPayloadPkg: Runtime MMCONF]

["Andrew Fish" <afish@apple.com>]

Ray,

Here is my take and I think this is what Laszlo’s comments don’t make clear. I agree with you that the rote process steps should be very clear, but I think what Laszlo is pointing out that best practices and current thinking evolve over time and are hard to capture in words. 

So I think our challenge is to step back and write process documentation that make it easy to get started., but also make it easy to get the feedback of what the community think is best practices. I kind of feel right now that our process documents are biased towards people who work on on the edk2 day to day, and that makes it hard to bring on new members. 

I think the path forward is making it easy for the developers to take the right steps to get started so the community can give them feed back. This feedback is ultimately the current thinking of the community, but we also need think about how to make it easy to get started. So how do we document the process steps, that make it easy for the community to offer comments on the changes? 

One of the ways we solved this kind of problem at Apple, is we make the person we just hired the owner of the getting started guide. I think the goal is how do we make it easy for a new contributor to get he value of the feedback and knowledge of the community  of experts. 

But I think the solution is not to document everything we do, but to document the path of least resistance to join the community. And that is going to require people not in the community reviewing the documentation. We are too biased and can not do it by our selves. 

Thanks,

Andrew Fish

> On Sep 17, 2020, at 9:39 PM, Ni, Ray <ray.ni@intel.com> wrote:
> 
> Laszlo,
> I support your idea of having a meaningful description for BZ, for commit message, for code comments.
> 
> Thinking from 1 or 2 years from now, the simple message we created may help nothing to remind me or others why the changes were made.
> 
> We cannot reply on people's memories and even the people that have the memories may left the community.
> 
> So, documentation is necessary.
> 
> But I remember that our development process document in WIKI doesn't require anything on the commit message perspective.
> 
> IMO, at least the commit message should contain:
> * current status or reason(fail, lack of a feature, bad coding style)
> * impact of the change or result (fail to pass, feature enabled, coding style improved)
> 
> Can someone help to emphasize the requirement in the WIKI?
> 
> Thanks,
> Ray
> 
> 
> 
> 
>