Minor typo below: On Fri, Aug 07, 2020 at 18:04:47 -0700, 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 <ler...@redhat.com> > Cc: Andrew Fish <af...@apple.com> > Cc: Leif Lindholm <l...@nuviainc.com> > Signed-off-by: Michael D Kinney <michael.d.kin...@intel.com> > --- > EDK-II-Code-First-Process.md | 182 +++++++++++++++++++++++++++++++++++ > 1 file changed, 182 insertions(+) > create mode 100644 EDK-II-Code-First-Process.md > > 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
Drop "a"? Reviewed-by: Leif Lindholm <l...@nuviainc.com> > + * 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. > -- > 2.21.0.windows.1 > -=-=-=-=-=-=-=-=-=-=-=- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#64395): https://edk2.groups.io/g/devel/message/64395 Mute This Topic: https://groups.io/mt/76061237/21656 Group Owner: devel+ow...@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com] -=-=-=-=-=-=-=-=-=-=-=-
