From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from nwk-aaemail-lapp02.apple.com (nwk-aaemail-lapp02.apple.com [17.151.62.67]) by mx.groups.io with SMTP id smtpd.web11.50154.1597080981434866488 for ; Mon, 10 Aug 2020 10:36:22 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@apple.com header.s=20180706 header.b=IWsjdVf4; spf=pass (domain: apple.com, ip: 17.151.62.67, mailfrom: afish@apple.com) Received: from pps.filterd (nwk-aaemail-lapp02.apple.com [127.0.0.1]) by nwk-aaemail-lapp02.apple.com (8.16.0.43/8.16.0.42) with SMTP id 07AHF7jT006460; Mon, 10 Aug 2020 10:36:19 -0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=apple.com; h=from : message-id : content-type : mime-version : subject : date : in-reply-to : cc : to : references; s=20180706; bh=+Sskf1MUTYNWS/zh9LRBctUpHDOQ1UnAfLl1P7C2nMQ=; b=IWsjdVf4KvvxBOojtvElnyUsnChT5j25HVzj00THFvIqSGdPbTXfwj65fSWDO8FaHD3c 7IRBIQHSBk+JCxsXtxVpFzf8HbX3EBn6oZpcb11JsJGHlrloK3VvhMO2cfOL8NmMj1qg 88k5yEZSnfIASKEOhwbiwxMKVyOHj1iqBuO+M4MSE9baUICgWHxc9+MD32cvQIH7SyA2 OZwjeZTi5Mmv0PhbHaVnu7v96VEjq18duIDMg4jTt39GA24yKG2fB4m0K7jcFqAv3O8j eavYib7ZbI9MYUpOznZAhL81+rxp790azwqfV57tPz7EQpWgpCxFOdRynqfCVjZUs7Nb pA== Received: from rn-mailsvcp-mta-lapp02.rno.apple.com (rn-mailsvcp-mta-lapp02.rno.apple.com [10.225.203.150]) by nwk-aaemail-lapp02.apple.com with ESMTP id 32srmfvsk8-2 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128 verify=NO); Mon, 10 Aug 2020 10:36:19 -0700 Received: from rn-mailsvcp-mmp-lapp01.rno.apple.com (rn-mailsvcp-mmp-lapp01.rno.apple.com [17.179.253.14]) by rn-mailsvcp-mta-lapp02.rno.apple.com (Oracle Communications Messaging Server 8.1.0.6.20200729 64bit (built Jul 29 2020)) with ESMTPS id <0QEU00301ZKJV040@rn-mailsvcp-mta-lapp02.rno.apple.com>; Mon, 10 Aug 2020 10:36:19 -0700 (PDT) Received: from process_milters-daemon.rn-mailsvcp-mmp-lapp01.rno.apple.com by rn-mailsvcp-mmp-lapp01.rno.apple.com (Oracle Communications Messaging Server 8.1.0.6.20200729 64bit (built Jul 29 2020)) id <0QEU00B00Z45IB00@rn-mailsvcp-mmp-lapp01.rno.apple.com>; Mon, 10 Aug 2020 10:36:19 -0700 (PDT) X-Va-A: X-Va-T-CD: 13715775cfe6ed78bc954dbcb503dbb2 X-Va-E-CD: 168d6537e80995189ab8d08a92191586 X-Va-R-CD: 238bfd130e544126df08935334953967 X-Va-CD: 0 X-Va-ID: e872f420-79a0-413b-9b20-832b5d0e0604 X-V-A: X-V-T-CD: 13715775cfe6ed78bc954dbcb503dbb2 X-V-E-CD: 168d6537e80995189ab8d08a92191586 X-V-R-CD: 238bfd130e544126df08935334953967 X-V-CD: 0 X-V-ID: ab2aeb61-b9a9-4c01-a486-a0bcfdb06ae3 X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.235,18.0.687 definitions=2020-08-10_14:2020-08-06,2020-08-10 signatures=0 Received: from [17.235.18.161] (unknown [17.235.18.161]) by rn-mailsvcp-mmp-lapp01.rno.apple.com (Oracle Communications Messaging Server 8.1.0.6.20200729 64bit (built Jul 29 2020)) with ESMTPSA id <0QEU0051IZKGIC00@rn-mailsvcp-mmp-lapp01.rno.apple.com>; Mon, 10 Aug 2020 10:36:18 -0700 (PDT) From: "Andrew Fish" Message-id: <38A7BE23-0341-4523-A58E-D1DDCC5FAEED@apple.com> MIME-version: 1.0 (Mac OS X Mail 13.4 \(3608.80.23.2.2\)) Subject: Re: [Wiki][Patch V2] Add EDK II Code First Process Wiki Page Date: Mon, 10 Aug 2020 10:36:16 -0700 In-reply-to: <17ba18c5-744c-bd7b-bd1a-e08262f43dac@redhat.com> Cc: Mike Kinney , edk2-devel-groups-io , Leif Lindholm To: Laszlo Ersek References: <20200808010448.39460-1-michael.d.kinney@intel.com> <17ba18c5-744c-bd7b-bd1a-e08262f43dac@redhat.com> X-Mailer: Apple Mail (2.3608.80.23.2.2) X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.235,18.0.687 definitions=2020-08-10_14:2020-08-06,2020-08-10 signatures=0 Content-type: multipart/alternative; boundary="Apple-Mail=_028396C6-BDDA-46A6-A54B-64E12C82DD30" --Apple-Mail=_028396C6-BDDA-46A6-A54B-64E12C82DD30 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii Mike, Looks like a good start. Acked-by: Andrew Fish Thanks, Andrew Fish > On Aug 10, 2020, at 2:17 AM, Laszlo Ersek wrote: >=20 > On 08/08/20 03:04, Michael D Kinney wrote: >> Based on the following RFC: >>=20 >> https://edk2.groups.io/g/rfc/message/258 >>=20 >> 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. >>=20 >> 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 >=20 > Sorry, I'm only seeing now that there's a v2. >=20 > AFAICT (from comparing the emails), the only difference with v1 is > Leif's email address. So >=20 > Acked-by: Laszlo Ersek > >=20 > Thanks > Laszlo >=20 >> 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=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-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=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 = 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. --Apple-Mail=_028396C6-BDDA-46A6-A54B-64E12C82DD30 Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=us-ascii 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>

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 |
+| --- =             &n= bsp;| --- =             &n= bsp;     | ---     |
+| `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 =             &n= bsp; |
+| --- =             &n= bsp;     | --- =             &n= bsp;     | --- =             &n= bsp;     |
+| `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 |
+| --- =             &n= bsp;| --- =             &n= bsp;     | ---     |
+| `gSomeGuid`      | = `gBz1234SomeGuid`     | =         |
+
+Local identifiers, including module-global ones (m-prefixed) = do not require a
+BZ = prefix.

= --Apple-Mail=_028396C6-BDDA-46A6-A54B-64E12C82DD30--