From nobody Mon Nov 25 22:48:07 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of groups.io designates 66.175.222.12 as permitted sender) client-ip=66.175.222.12; envelope-from=bounce+27952+63889+1787277+3901457@groups.io; helo=web01.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.12 as permitted sender) smtp.mailfrom=bounce+27952+63889+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=intel.com ARC-Seal: i=1; a=rsa-sha256; t=1596848591; cv=none; d=zohomail.com; s=zohoarc; b=Ah6xVuD2rwLLODxoXANAG83RuAkyy0jTGWhhypp23XEzTtp2dMUGpVQ0QdnGH10MqCGuZUz+q5hy+OfM/qn9bIrxnR0yXsMRsx8pgpnTAZw01SFq2oB1r0LHMyNROKOGNdsL0yD6B5BWdL97xNTcOHwaeny40k7ZJ11kO+dkvVc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1596848591; h=Content-Transfer-Encoding:Cc:Date:From:List-Id:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:Sender:Subject:To; bh=xZIQtglYicXgzoD/TkHrBwbrDK66F3FhKs34SjllQhI=; b=h+QtzpRVMF5osBnP2u9eFjJTVr41D3Ls6gzcym4k0MWkmLRtiJj9y21hwpbpIfeqsEc+9tAUa/XEZfNvQPO+ht/3b8tYzetaLxAichEdrr2Wbi5x0Bssf5sLIjr51q5RZW+77DmAZgW9Ys3Lc91ESLTlrGHDGHAkpLBrgwVq1Cw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.12 as permitted sender) smtp.mailfrom=bounce+27952+63889+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) header.from= Received: from web01.groups.io (web01.groups.io [66.175.222.12]) by mx.zohomail.com with SMTPS id 1596848591680157.43624915211092; Fri, 7 Aug 2020 18:03:11 -0700 (PDT) Return-Path: X-Received: by 127.0.0.2 with SMTP id Sn9yYY1788612x1bzCqRxWbx; Fri, 07 Aug 2020 18:03:11 -0700 X-Received: from mga01.intel.com (mga01.intel.com [192.55.52.88]) by mx.groups.io with SMTP id smtpd.web12.2456.1596848590290833686 for ; Fri, 07 Aug 2020 18:03:10 -0700 IronPort-SDR: PFcR8ZhMyg/2hEWR9QQTYDwpkDazzSI7ZeVgv20hUOwSpGO7rwYZ06uqEY51ziX9wYTC6X3RSv vydx81PjAA8g== X-IronPort-AV: E=McAfee;i="6000,8403,9706"; a="171281548" X-IronPort-AV: E=Sophos;i="5.75,447,1589266800"; d="scan'208";a="171281548" X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False X-Received: from orsmga004.jf.intel.com ([10.7.209.38]) by fmsmga101.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 07 Aug 2020 18:03:09 -0700 IronPort-SDR: KsjfXKyEtxcQ/Lp3ti/5KvLJro1vGiPWKZnPNw7ERPkJfOMlTcArrvqF+KyhZKIsNMJyOTLnSZ v3AoIzQr5JZg== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.75,447,1589266800"; d="scan'208";a="438070993" X-Received: from mdkinney-mobl2.amr.corp.intel.com ([10.254.118.158]) by orsmga004.jf.intel.com with ESMTP; 07 Aug 2020 18:03:09 -0700 From: "Michael D Kinney" To: devel@edk2.groups.io Cc: Laszlo Ersek , Andrew Fish , Leif Lindholm Subject: [edk2-devel] [Wiki][Patch] Add EDK II Code First Process Wiki Page Date: Fri, 7 Aug 2020 18:03:05 -0700 Message-Id: <20200808010305.1576-1-michael.d.kinney@intel.com> MIME-Version: 1.0 Precedence: Bulk List-Unsubscribe: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,michael.d.kinney@intel.com X-Gm-Message-State: 6yTC1HuzrM6KNANxm6oiHL8wx1787277AA= Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1596848591; bh=UOxEhml2z0vyktfFU1NTHezMdkNcuPdkK0Nl5WDmTQI=; h=Cc:Date:From:Reply-To:Subject:To; b=Xds6Uq0+LUSvJSoYDaHIT8fx5q5B1SeTLDFGiLJGP+RM7SNK9Dq6TUBek8GoRX5p7XC 6Hap+nEVCibnO0f8fPW7I0IW2OixPfD136qmW5VkzqNzpDj5njL9cpKQFaH1NGouxeDP7 GAMvnoX3N7KxlrdkLOHS6mxnNmIDX+bgpzw= X-ZohoMail-DKIM: pass (identity @groups.io) Content-Type: text/plain; charset="utf-8" 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 Acked-by: Laszlo Ersek --- 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 ad= ded +to UEFI Forum specifications after first having been designed and prototyp= ed +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 t= he +development (of both specification and code) happens in the open. The resu= lting +specification update is then submitted to the appropriate working group as= an +Engineering Change Request (ECR), and voted on. For the UEFI Forum, this i= s 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 specifi= cation +updates and reference implementations and new repositories under +[TianoCore GitHub](https://github.com/tianocore) dedicated to hold "code f= irst". + +# TianoCore Bugzilla + +[TianoCore Bugzilla](bugzilla.tianocore.org) has a product categories for + * ACPI Specification + * UEFI Shell Specification=20 + * 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-stagin= g) +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 fi= les) +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 affec= ting + multiple specifications, but at that point we can track it with multiple=20 + TianoCore Bugzilla entries. + +## Specification Text Template + +The following is a template of specification text changes using the GitHub=20 +flavor of markdown. The title and complete description of the specificati= on +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 bas= ed +on feedback from the industry standard forums. The contents of the specif= ication +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 Versio= n 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 appr= opriate +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 t= he +relevant repositories for each Bugzilla. The branch names must use the fo= llowing +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 Bugzi= lla +is be the one naming the branch. + +# Source Code + +In order to ensure draft code does not accidentally leak into production u= se, +and to signify when the changeover from draft to final happens, *all* new = or +modified[1] identifiers must be prefixed with the relevant BZ#### identifi= ers. + +* [1] Modified in a non-backwards-compatible way. If, for example, a stati= cally + 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 pr= efix. + +| Released in spec | Draft version in tree | Comment | +| --- | --- | --- | +| `gSomeGuid` | `gBz1234SomeGuid` | | + +Local identifiers, including module-global ones (m-prefixed) do not requir= e a +BZ prefix. --=20 2.21.0.windows.1 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#63889): https://edk2.groups.io/g/devel/message/63889 Mute This Topic: https://groups.io/mt/76061221/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-