-----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