From: firstname.lastname@example.org <email@example.com> On
Behalf Of Laszlo Ersek
Sent: Monday, January 20, 2020 10:42 AM
To: firstname.lastname@example.org; leif@...;
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 newfeatures can be added to UEFI
forum specifications after first having been designedand prototyped in the
open.features happen in the
This process lets changes and the development of new
open, without violating the UEFI forum bylaws whichprevent publication of
code for in-draft features/changes.the change is that the
The process does not in fact change the UEFI bylaws -
development (of both specification and code) happensin the open. The resulting
specification update is then submitted to theappropriate working goup as an
Engineering Change Request (ECR), and voted on. Forthe UEFI Forum, this is a
change in workflow, not a change in process.access restricted to UEFI
ECRs are tracked in a UEFI Forum Mantis instance,
Forum Members. TianoCore will enable this new processby providing areas on
https://bugzilla.tianocore.org/ to track bothspecification updates and
reference implementations and new repositories underfirst".
https://github.com/tianocore/ dedicated to hold "code
bugzilla.tianocore.oorg will have a product category
* ACPI Specificationfor
* PI Specification
* UEFI Specification
Each product category will have a separate components
* Specificationchanges and the source code.
* Reference implementation
New repositories will be added for holding the text
affected source repository.
Specification text changes will be held within the
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 aspecification change affecting multiple
specifications, but at that point we can track itwith multiple BZ entries)
Initially, edk2-spec-update will be created to hold
implementations. Additional repositories forimplementing reference features in
additional open source projects can be added in thefuture, as required.
I recommend using branches in the existing edk2-staging
repository for changes that only impact EDK II firmware
Bugzilla in the appropriate
## Intended workflow
The entity initiating a specifiation update raises a
area in bugzilla.tianocore.org. This entry containsthe outline of the change,
and the full initial draft text is attached.How does this play together with *patches* for specs
Attaching patches to BZs is not good practice. Should
we attach complete
renderings of the patched (huge) specs?
especially if between
If multiple specification updates are interdependent,
different specifications, then multiple bugzillaentries should be created.
These bugzilla entries *must* be linked together withdependencies.
be created in the relevant
After the BZs have been created, new branches should
repositories for each bugzilla - the branch namesshould be BZ####, where ####
describes the bugzilla ID assigned, optionallyfollowed by a '-' and something
more descriptive. If multipls bugzilla entries mustcoexist on a single branch,
one of them is designated the 'top-level', withdependencies properly tracked.
That BZ will be the one naming the branch.leak into production use,
## Source code
In order to ensure draft code does not accidentally
and to signify when the changeover from draft tofinal happens, *all* new or
modified identifiers need to be prefixed with therelevant BZ####.
for example, a statically
 Modified in a non-backwards-compatible way. If,
sized array is grown - this does not need to beprefixed. (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 eachaffected codebase.
| Released in spec | Draft version in tree | Comment
| --- | --- | ---|
| FunctionName | Bz1234FunctionName | EDK2|
| function_name | bz1234_function_name | Linux|
| HEADER_MACRO | BZ1234_HEADER_MACRO | EDK2,Linux |
'm') go before the BZ prefix.
Variable prefixes indicating global scope ('g' or
I prefer Alternative 1 to follow EDK II C Coding Standard.
Alternative 2)'m') go after the BZ prefix.
Variable prefixes indicating global scope ('g' or
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
anything specific that's missing from the proposal, but
I'm quite sure
we'll find corner cases in practice.