From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-wr1-f68.google.com (mail-wr1-f68.google.com [209.85.221.68]) by mx.groups.io with SMTP id smtpd.web10.71885.1597773679819918160 for ; Tue, 18 Aug 2020 11:01:20 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@nuviainc-com.20150623.gappssmtp.com header.s=20150623 header.b=PPKrSFOm; spf=pass (domain: nuviainc.com, ip: 209.85.221.68, mailfrom: leif@nuviainc.com) Received: by mail-wr1-f68.google.com with SMTP id p20so19125996wrf.0 for ; Tue, 18 Aug 2020 11:01:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nuviainc-com.20150623.gappssmtp.com; s=20150623; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=26bZ9aX20vSIULOtNhupJjHyBNvGIyJ6I4MGwp3st1k=; b=PPKrSFOmsCtlUKaZny6WXl5keJ91HTJ9s5VlHwhJy3ZHmzvgBoHG59fzGHuNfvhhMA 0iEjRcVrMbyJIP8s+KWaP0GGBSM5k2+vgKSfj+7Mspnz+1ZUBaNgas34QrzSHDkQz0y/ EwiF3n5YhptFY5qG8vkV5VNVxXJ3g7VSn6c9TZTKEhPW4P8MnsoxmYLXhLt3HeuTpLnY I8oE0IHXezCrXjMVl/1u6oZ5cVJbxXYQ2ZD064fz+rJoLOmZf8FFt43TxM80Uux7N1Tk Lgl9jz3sfXICuDrcJkfKhJdPnLLu0V0bbTn/cMgtqiwsCoUtaa1NaUE+3ylXOsN0UEV8 1B5A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=26bZ9aX20vSIULOtNhupJjHyBNvGIyJ6I4MGwp3st1k=; b=s0CoqSrm8EuWLJNbiCQCoou46LpXocCsh5zGfMM8rzozUusJfKDvv6ln44miU5fRsh AeiTjdBRYJNRTRr0PJc402p6IFfWHUG6r6meE8BAMzmkA2h+Imw7ot75dsTDghicRW8c TTiPNeIfZAuvII5RGYKfoppQqRtrX4+SPmaOoScQi7iZ/xgbf6HIIYgM3k2g4zLpWma6 +Shz22pGYhHe3IO/PLzmfuAcsShoZ6YW29bG4/klRhxedo9MgAkVNRBYvB0lgGXJLYmS uvT7YiWZ314tfZUn2bsvhiO73Jvy53n3Rs5+PM7YI2tqk7mZhr7csZh+aQXZirtNjY00 CJmQ== X-Gm-Message-State: AOAM5302xodixr3eINMltQLmnxCawMMwyX8vF0Vlp1i3YF/APMtKTeNX PyzDZ5Rj+EFGC4hMP8lro4iu8Q== X-Google-Smtp-Source: ABdhPJxfJ1xBeCgG09QSuVMDwsKzhL2JvYF6vzkRpEeE5R7EXZOpsHm/gQ5S5UBRWpeNnaee1egdVQ== X-Received: by 2002:adf:9ec1:: with SMTP id b1mr21142570wrf.171.1597773678136; Tue, 18 Aug 2020 11:01:18 -0700 (PDT) Return-Path: Received: from vanye ([2001:470:1f09:12f0:b26e:bfff:fea9:f1b8]) by smtp.gmail.com with ESMTPSA id k13sm896413wmj.14.2020.08.18.11.01.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 18 Aug 2020 11:01:17 -0700 (PDT) Date: Tue, 18 Aug 2020 19:01:15 +0100 From: "Leif Lindholm" To: Michael D Kinney Cc: devel@edk2.groups.io, Laszlo Ersek , Andrew Fish Subject: Re: [Wiki][Patch V2] Add EDK II Code First Process Wiki Page Message-ID: <20200818180115.GA17439@vanye> References: <20200808010448.39460-1-michael.d.kinney@intel.com> MIME-Version: 1.0 In-Reply-To: <20200808010448.39460-1-michael.d.kinney@intel.com> User-Agent: Mutt/1.10.1 (2018-07-13) Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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 > 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 Drop "a"? Reviewed-by: Leif Lindholm > + * 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 >