Re: [Wiki][Patch V2] Add EDK II Code First Process Wiki Page

["Andrew Fish" <afish@apple.com>]

[-- Attachment #1: Type: text/plain, Size: 9442 bytes --]

Mike,

Looks like a good start.

Acked-by: Andrew Fish <afish@apple.com>

Thanks,

Andrew Fish

> On Aug 10, 2020, at 2:17 AM, Laszlo Ersek <lersek@redhat.com> wrote:
> 
> On 08/08/20 03:04, Michael D Kinney wrote:
>> Based on the following RFC:
>> 
>>    https://edk2.groups.io/g/rfc/message/258
>> 
>> Additional updates:
>> * Add examples of all specifications currently maintained by
>>  the UEFI Forums.
>> * Added specification change template using a CC-BY-4.0 license.
>> * Add source code example for an enum value
>> * Minor grammar updates to change from an RFC proposal to an
>>  active process.
>> 
>> Cc: Laszlo Ersek <lersek@redhat.com>
>> Cc: Andrew Fish <afish@apple.com>
>> Cc: Leif Lindholm <leif@nuviainc.com>
>> Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com>
>> ---
>> EDK-II-Code-First-Process.md | 182 +++++++++++++++++++++++++++++++++++
>> 1 file changed, 182 insertions(+)
>> create mode 100644 EDK-II-Code-First-Process.md
> 
> Sorry, I'm only seeing now that there's a v2.
> 
> AFAICT (from comparing the emails), the only difference with v1 is
> Leif's email address. So
> 
> Acked-by: Laszlo Ersek <lersek@redhat.com <mailto:lersek@redhat.com>>
> 
> Thanks
> Laszlo
> 
>> diff --git a/EDK-II-Code-First-Process.md b/EDK-II-Code-First-Process.md
>> new file mode 100644
>> index 0000000..d5c938e
>> --- /dev/null
>> +++ b/EDK-II-Code-First-Process.md
>> @@ -0,0 +1,182 @@
>> +The EDK II Code First Process is 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 group 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 enables this new process by providing areas on
>> +[TianoCore Bugzilla](https://bugzilla.tianocore.org) to track both specification
>> +updates and reference implementations and new repositories under
>> +[TianoCore GitHub](https://github.com/tianocore) dedicated to hold "code first".
>> +
>> +# TianoCore Bugzilla
>> +
>> +[TianoCore Bugzilla](bugzilla.tianocore.org) has a product categories for
>> +  * ACPI Specification
>> +  * UEFI Shell Specification 
>> +  * UEFI Platform Initialization Distribution Packaging Specification
>> +  * UEFI Platform Initialization Specification Specification
>> +  * UEFI Specification
>> +
>> +Each product category has separate components for
>> +  * Specification
>> +  * Reference implementation
>> +
>> +# TianoCore GitHub
>> +
>> +Reference implementations targeting the EDK II open source project are held
>> +in branches in the [edk2-staging](https://github.com/tianocore/edk2-staging)
>> +repository.
>> +
>> +Additional repositories for implementing reference features in additional open
>> +source projects can be added in the future, as required.
>> +
>> +Specification text changes are held within the affected source repository,
>> +using the GitHub flavor of markdown, in a file (or split across several files)
>> +with .md suffix.  Multiple files are required if changes impact multiple
>> +specifications or if the specification is large and is easier to maintain
>> +if the changes are split across multiple files.
>> +
>> +* NOTE: This one may break down where we have a specification change affecting
>> +  multiple specifications, but at that point we can track it with multiple 
>> +  TianoCore Bugzilla entries.
>> +
>> +## Specification Text Template
>> +
>> +The following is a template of specification text changes using the GitHub 
>> +flavor of markdown.  The title and complete description of the specification
>> +changes must be provided in the specification text along with the name and
>> +version of the specification the change applies.  The `Status` of the
>> +specification change always starts in the `Draft` state and is updated based
>> +on feedback from the industry standard forums.  The contents of the specification
>> +text are required to use the
>> +[Creative Commons Attribution 4.0 International](https://spdx.org/licenses/CC-BY-4.0.html)
>> +license using a `SPDX-License-Identifier` statement.
>> +
>> +```
>> +# Title: [Must be Filled In]
>> +
>> +# Status: [Status]
>> +
>> +[Status] must be one of the following:
>> +* Draft
>> +* Submitted to industry standard forum
>> +* Accepted by industry standard forum
>> +* Accepted by industry standard forum with modifications
>> +* Rejected by industry standard forum
>> +
>> +# Document: [Title and Version]
>> +
>> +Here are some examples of [Title and Version]:
>> +* UEFI Specification Version 2.8
>> +* ACPI Specification Version 6.3
>> +* UEFI Shell Specification Version 2.2
>> +* UEFI Platform Initialization Specification Version 1.7
>> +* UEFI Platform Initialization Distribution Packaging Specification Version 1.1
>> +
>> +# License
>> +
>> +SPDX-License-Identifier: CC-BY-4.0
>> +
>> +# Submitter: [TianoCore Community](https://www.tianocore.org)
>> +
>> +# Summary of the change
>> +
>> +Required Section
>> +
>> +# Benefits of the change
>> +
>> +Required Section
>> +
>> +# Impact of the change
>> +
>> +Required Section
>> +
>> +# Detailed description of the change [normative updates]
>> +
>> +Required Section
>> +
>> +# Special Instructions
>> +
>> +Optional Section
>> +```
>> +
>> +# Intended workflow
>> +
>> +The entity initiating a specification change enters a Bugzilla in the appropriate
>> +area of [TianoCore Bugzilla](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 Bugzillas have been created, new branches should be created in the
>> +relevant repositories for each Bugzilla.  The branch names must use the following
>> +format where #### is the Bugzilla ID and <Brief Description> is an optional
>> +description of the change.
>> +
>> +    BZ####-<Brief Description>
>> +
>> +If multiple Bugzilla entries must coexist on a single branch, one of them is
>> +designated the _top-level_, with dependencies properly tracked. That Bugzilla
>> +is 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 must be prefixed with the relevant BZ#### identifiers.
>> +
>> +* [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 require 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 code base.
>> +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.
>> +
>> +| Released in spec      | Draft version in tree | Comment               |
>> +| ---                   | ---                   | ---                   |
>> +| `typedef SOME_STRUCT` | `BZ1234_SOME_STRUCT`  | Typedef only [2]      |
>> +| `StructField`         | `Bz1234StructField`   | In existing struct[3] |
>> +| `typedef SOME_ENUM`   | `BZ1234_SOME_ENUM`    | Typedef only [2]      |
>> +| `EnumValue`           | `BzEnumValue`         | In existing enum[3]   |
>> +
>> +* [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 struct or enum do not need prefix, the
>> +      struct or enum already carried the prefix.
>> +
>> +Variable prefixes indicating global scope ('g' or 'm') go before the BZ prefix.
>> +
>> +| Released in spec | Draft version in tree | Comment |
>> +| ---              | ---                   | ---     |
>> +| `gSomeGuid`      | `gBz1234SomeGuid`     |         |
>> +
>> +Local identifiers, including module-global ones (m-prefixed) do not require a
>> +BZ prefix.


[-- Attachment #2: Type: text/html, Size: 22160 bytes --]