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


Michael D Kinney
 

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@...;
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


Join rfc@edk2.groups.io to automatically receive all group messages.