Re: [edk2-devel] [edk2-rfc] [RFC] code-first process for UEFI-forum specifications

["Michael D Kinney" <michael.d.kinney@intel.com>]

Leif,

A few comments included below.

Thanks,

Mike

> -----Original Message-----
> From: devel@edk2.groups.io <devel@edk2.groups.io> On
> Behalf Of Laszlo Ersek
> Sent: Monday, January 20, 2020 10:42 AM
> To: rfc@edk2.groups.io; leif@nuviainc.com;
> devel@edk2.groups.io
> Subject: Re: [edk2-devel] [edk2-rfc] [RFC] code-first
> process for UEFI-forum specifications
> 
> On 01/20/20 17:58, Leif Lindholm wrote:
> > This is a proposal for a process by which new
> features can be added to UEFI
> > forum specifications after first having been designed
> and prototyped in the
> > open.
> >
> > This process lets changes and the development of new
> features happen in the
> > open, without violating the UEFI forum bylaws which
> prevent publication of
> > code for in-draft features/changes.
> >
> > The process does not in fact change the UEFI bylaws -
> the change is that the
> > development (of both specification and code) happens
> in the open. The resulting
> > specification update is then submitted to the
> appropriate working goup as an
> > Engineering Change Request (ECR), and voted on. For
> the UEFI Forum, this is a
> > change in workflow, not a change in process.
> >
> > ECRs are tracked in a UEFI Forum Mantis instance,
> access restricted to UEFI
> > Forum Members. TianoCore will enable this new process
> by providing areas on
> > https://bugzilla.tianocore.org/ to track both
> specification updates and
> > reference implementations and new repositories under
> > https://github.com/tianocore/ dedicated to hold "code
> first".
> >
> >
> > ## Bugzilla
> >
> > bugzilla.tianocore.oorg will have a product category
> each for
> 
> s/oorg/org/
> 
> >   * ACPI Specification
> >   * PI Specification
> >   * UEFI Specification
> >
> > Each product category will have a separate components
> for
> >   * Specification
> >   * Reference implementation
> >
> >
> > ## Github
> > New repositories will be added for holding the text
> changes and the source code.
> >
> > Specification text changes will be held within the
> affected source repository.
> 
> This seems to require that the specifications be
> available as something
> "patchable" (e.g. GitBook source code), and offered in
> some public git repo.
> 

I recommend we use MarkDown.  GitHub flavored MarkDown
may be a good choice so an ECR can be viewed from the
web view of GitHub.  This also support text based patch
reviews of the ECR content.

> > (This one may break down where we have a
> specification change affecting multiple
> > specifications, but at that point we can track it
> with multiple BZ entries)
> >
> > Initially, edk2-spec-update will be created to hold
> the reference
> > implementations. Additional repositories for
> implementing reference features in
> > additional open source projects can be added in the
> future, as required.

I recommend using branches in the existing edk2-staging
repository for changes that only impact EDK II firmware
components/tools.

> >
> >
> > ## Intended workflow
> > The entity initiating a specifiation update raises a
> Bugzilla in the appropriate
> > area in bugzilla.tianocore.org. This entry contains
> the outline of the change,
> > and the full initial draft text is attached.
> 
> How does this play together with *patches* for specs
> (see above)?
> Attaching patches to BZs is not good practice. Should
> we attach complete
> renderings of the patched (huge) specs?
> 
> >
> > If multiple specification updates are interdependent,
> especially if between
> > different specifications, then multiple bugzilla
> entries should be created.
> > These bugzilla entries *must* be linked together with
> dependencies.
> >
> > After the BZs have been created, new branches should
> be created in the relevant
> > repositories for each bugzilla - the branch names
> should be BZ####, where ####
> > describes the bugzilla ID assigned, optionally
> followed by a '-' and something
> > more descriptive. If multipls bugzilla entries must
> coexist on a single branch,
> 
> s/multipls/multiple/
> 
> > one of them is designated the 'top-level', with
> dependencies properly tracked.
> > That BZ will be the one naming the branch.
> >
> >
> > ## Source code
> > In order to ensure draft code does not accidentally
> leak into production use,
> > and to signify when the changeover from draft to
> final happens, *all* new or
> > modified[1] identifiers need to be prefixed with the
> relevant BZ####.
> >
> > [1] Modified in a non-backwards-compatible way. If,
> for example, a statically
> >     sized array is grown - this does not need to be
> prefixed. (Question: but a
> >     tag in a comment?)
> >

It would be good to clarify when the BZ### prefix is required
and not required and to describe a few more use cases.  Here 
are a few.  I am sure this list will be expanded when real
examples are implemented.

1) New/modified interfaces require prefix.
  a) New structures.  Only top level struct require a prefix.  Fields and sub structures do not.
2) New public header file names need prefix (e.g. Bz0001MyNewProtocol.h)
3) New GUID global variables need a prefix (e.g. gBz0001MyNewProtocolGuid)
4) Adding a field, enum, or #define to existing interface require a prefix
5) Internal interfaces and implementation elements do not need a prefix.

> > The tagging must follow the coding style used by each
> affected codebase.
> > Examples:
> >
> > | Released in spec | Draft version in tree | Comment
> |
> > | ---              | ---                   | ---
> |
> > | FunctionName     | Bz1234FunctionName    | EDK2
> |
> > | function_name    | bz1234_function_name  | Linux
> |
> > | HEADER_MACRO     | BZ1234_HEADER_MACRO   | EDK2,
> Linux |
> >
> > Alternative 1)
> > Variable prefixes indicating global scope ('g' or
> 'm') go before the BZ prefix.
> >

I prefer Alternative 1 to follow EDK II C Coding Standard.

> > Alternative 2)
> > Variable prefixes indicating global scope ('g' or
> 'm') go after the BZ prefix.
> 
> Sounds good to me in general.
> 
> I think we'll have to work out the nuances of the
> coding style in
> practice, while actually developing such additions. I
> can't name
> anything specific that's missing from the proposal, but
> I'm quite sure
> we'll find corner cases in practice.
> 
> Thanks
> Laszlo
> 
> 
>