From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from us-smtp-delivery-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.81]) by mx.groups.io with SMTP id smtpd.web12.41065.1597051055873006455 for ; Mon, 10 Aug 2020 02:17:36 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@redhat.com header.s=mimecast20190719 header.b=e/hhqcpV; spf=pass (domain: redhat.com, ip: 207.211.31.81, mailfrom: lersek@redhat.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1597051055; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=gGuINTWH/gM7jmc91iYWXH57gtXLRkSB5TzsWyB/0vE=; b=e/hhqcpVyvbNVQup9ldgTc8rvz98TPrOMdId4wzOiK3z8tchvhFtoNpxoZpWzPH61XyOE3 woa0p8b00U3hNj69AHq6PPT/6QG3sq4kyBcdqcwKz6ig7CL8W8bSRoxXYMb/VjdEOamN8p i4PXcgdSrAfwscN8YKAMouwkpf2dqvQ= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-143-wHUpU64AOAaBD_eJVW9P6w-1; Mon, 10 Aug 2020 05:17:33 -0400 X-MC-Unique: wHUpU64AOAaBD_eJVW9P6w-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 0A9081005504; Mon, 10 Aug 2020 09:17:32 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-113-77.ams2.redhat.com [10.36.113.77]) by smtp.corp.redhat.com (Postfix) with ESMTP id ED91119C4F; Mon, 10 Aug 2020 09:17:30 +0000 (UTC) Subject: Re: [Wiki][Patch V2] Add EDK II Code First Process Wiki Page To: Michael D Kinney , devel@edk2.groups.io Cc: Andrew Fish , Leif Lindholm References: <20200808010448.39460-1-michael.d.kinney@intel.com> From: "Laszlo Ersek" Message-ID: <17ba18c5-744c-bd7b-bd1a-e08262f43dac@redhat.com> Date: Mon, 10 Aug 2020 11:17:30 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Firefox/52.0 Thunderbird/52.9.1 MIME-Version: 1.0 In-Reply-To: <20200808010448.39460-1-michael.d.kinney@intel.com> X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=lersek@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Language: en-US Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit 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 > 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 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 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 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. >