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

["Ni, Ray" <ray.ni@intel.com>]

> 
> ## 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,
> in the Github flavour of markdown, in a file (or split across several files)
> with .md suffix.

What's the case when multiple .MD files are needed?

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

> 
> 
> ## 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. But a tag in a
> 	comment would be *highly* recommended.

If a protocol is enhanced to provide more interfaces with increased revision number,
would you like the protocol name to be prefixed with BZ####?
Or just the new interfaces added to the protocol are prefixed the BZ####?
I think just prefixing the new interfaces can meet the purpose.

But the protocol definition is changed, it also needs to be prefixed according to this flow.
Can you clarify a bit more?

> 
> ### File names
> New public header files need the prefix. I.e. `Bz1234MyNewProtocol.h`
> Private header files do not need the prefix.
> 
> ### Contents
> 
> The tagging must follow the coding style used by each affected codebase.
> Examples:
> 
> | Released in spec      | Draft version in tree       | Comment                |
> | ---                   | ---                         | ---                    |
> | `FunctionName`        | `Bz1234FunctionName`        |                        |
> | `HEADER_MACRO`        | `BZ1234_HEADER_MACRO`       |                        |

If FunctionName or HEADER_MACRO is defined in non-public header files, I don't
think they require the prefix. Do you agree?
 
> For data structures or enums, any new or non-backwards-compatible structs or
> fields require a prefix. As above, growing an existing array in an existing
> struct requires no prefix.
> 
> | `typedef SOME_STRUCT` | `BZ1234_SOME_STRUCT`        | Typedef only [2]       |
> | `StructField`         | `Bz1234StructField`         | In existing struct[3]  |
> | `typedef SOME_ENUM`   | `BZ1234_SOME_ENUM`          | Typedef only [2]       |
> 
> [2] If the struct or enum definition is separate from the typedef in the public
>     header, the definition does not need the prefix.

What does "separate" mean?
Does it mean "struct or enum in the public header BzXXX.h don't need the prefix"?
If yes, then I think macros defined in BzXXX.h also don't need the prefix.

> [3] Individual fields in newly added typedefd struct do not need prefix, the
>     struct already carried the prefix.
> 
> Variable prefixes indicating global scope ('g' or 'm') go before the BZ prefix.
> 
> | `gSomeGuid`           | `gBz1234SomeGuid`           |                        |
> 
> Local identifiers, including module-global ones (m-prefixed) do not require a
> BZ prefix.

I think only the names (struct type name, enum type name, interface name, protocol/ppi name)
defined in public header files need the BZ prefix when the public header doesn't have prefix.
Right?