From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by mx.groups.io with SMTP id smtpd.web12.2477.1596848690623765895 for ; Fri, 07 Aug 2020 18:04:50 -0700 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: intel.com, ip: 134.134.136.100, mailfrom: michael.d.kinney@intel.com) IronPort-SDR: Q9IcJiJJVlbH8fi8t2oiqKZk3Jr2tpq6fY6q73FKpfEKQMoOX3PgEG24w8st/H3/VXGjgKjl+l tqyYEXb8jvjg== X-IronPort-AV: E=McAfee;i="6000,8403,9706"; a="217560208" X-IronPort-AV: E=Sophos;i="5.75,447,1589266800"; d="scan'208";a="217560208" X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga004.jf.intel.com ([10.7.209.38]) by orsmga105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 07 Aug 2020 18:04:49 -0700 IronPort-SDR: WTPOICE4aKZOCyfRWP0tVYUYjyk6WelNP960t329KX+Gn9aMWBQPxjZQBQiAs1Imk15YCbOBx0 tLVMO6dOfZkQ== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.75,447,1589266800"; d="scan'208";a="438071385" Received: from mdkinney-mobl2.amr.corp.intel.com ([10.254.118.158]) by orsmga004.jf.intel.com with ESMTP; 07 Aug 2020 18:04:49 -0700 From: "Michael D Kinney" To: devel@edk2.groups.io Cc: Laszlo Ersek , Andrew Fish , Leif Lindholm Subject: [Wiki][Patch V2] Add EDK II Code First Process Wiki Page Date: Fri, 7 Aug 2020 18:04:47 -0700 Message-Id: <20200808010448.39460-1-michael.d.kinney@intel.com> X-Mailer: git-send-email 2.21.0.windows.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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 Cc: Andrew Fish Cc: Leif Lindholm Signed-off-by: Michael D Kinney --- 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 + * 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 is an optional +description of the change. + + BZ####- + +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