[edk2-devel] [RFCv2] code-first process for UEFI-forum specifications

[Laszlo Ersek]

On 03/23/20 20:05, Leif Lindholm wrote:
> Changes to v2 of this proposal:
> - Feedback from Laszlo[a] and Mike[b] incorporated.
>   - I opted to view Mike's responses to Laszlo's questions as
>     accepted, as no follow-up was made.
> 
> Feedback from Felix[c] *not* incorporated, as while I agree with all
> of it, I am not convinced that information should go here, but should
> instead reside with the UEFI Forum. (This text documents the public
> part of the process - it would cause me slight impedance mismatch to
> have it also document the non-public part.)
> 
> [a] https://edk2.groups.io/g/devel/message/53422
> [b] https://edk2.groups.io/g/devel/message/53738
> [c] https://edk2.groups.io/g/devel/message/54453
> 
> /
>     Leif
> 
> ---
> 
> 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.org will have a product category each for
>   * 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,
> in the Github flavour of markdown, in a file (or split across several files)
> with .md suffix.
> (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)
> 
> Reference implementations targeting EDK2 will be held in branches on
> edk2-staging.
> Additional repositories for implementing reference features in
> additional open source projects can be added in the future, as required.
> 
> 
> ## 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.
> 
> 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 multiple bugzilla entries must coexist on a single branch,
> 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. But a tag in a
> 	comment would be *highly* recommended.
> 
> ### 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`       |                        |
> 
> 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.
> [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.

Acked-by: Laszlo Ersek <lersek at redhat.com>


-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.

View/Reply Online (#56299): https://edk2.groups.io/g/devel/message/56299
Mute This Topic: https://groups.io/mt/72500372/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub  [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-