> On Aug 10, 2020, at 11:36 AM, Samer El-Haj-Mahmoud > <samer.el-haj-mahm...@arm.com> wrote: > > Mike, > > Looks good as a starting point! > > Acked-by: Samer El-Haj-Mahmoud <samer.el-haj-mahm...@arm.com > <mailto:samer.el-haj-mahm...@arm.com>> > > > I do have a few questions on this sentence: "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." > > - For TianoCore, is the "affected source repository" this sentence is > referring to edk2-staging, or edk2? > > - If the proposed specification and associated code starts in a branch in > edk2-staging respiratory, when does it get accepted into edk2/edk2-platforms? > Is it when the proposed specification change reaches a certain status (such > as "accepted by industry standard forum"), or when the formal specification > (with that proposed change) is published by the UEFI Forum ? >
Samer, While in the “code 1st state” there are BZ# prefixes to types and globals. So when the code ends up in the specification the “code 1st” branch is going to need to get cleaned up for naming, and I assume we could remove the MD files before a patch is submitted to the edk2. We made extra work for ourselves, but we wanted it to be clear what was work in progress. Thanks, Andrew Fish > - Any guidance on the specification text md file(s) names (and location) > within the repository? > > - If the change includes some graphics, is there any guidance on inclusion of > the graphics files in the repository? > > Thanks, > --Samer > > > >> -----Original Message----- >> From: devel@edk2.groups.io <mailto:devel@edk2.groups.io> >> <devel@edk2.groups.io <mailto:devel@edk2.groups.io>> On Behalf Of Michael >> D Kinney via groups.io <http://groups.io/> >> Sent: Friday, August 7, 2020 9:07 PM >> To: devel@edk2.groups.io <mailto:devel@edk2.groups.io>; Kinney, Michael D >> <michael.d.kin...@intel.com <mailto:michael.d.kin...@intel.com>>; >> r...@edk2.groups.io <mailto:r...@edk2.groups.io> >> Cc: Laszlo Ersek <ler...@redhat.com <mailto:ler...@redhat.com>>; Andrew Fish >> <af...@apple.com <mailto:af...@apple.com>>; >> Leif Lindholm <l...@nuviainc.com <mailto:l...@nuviainc.com>> >> Subject: Re: [edk2-devel] [Wiki][Patch V2] Add EDK II Code First Process >> Wiki Page >> >> A version of this Wiki page is also provided here for review: >> >> https://github.com/mdkinney/edk2/wiki/EDK-II-Code-First-Process >> >> Mike >> >>> -----Original Message----- >>> From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of >> Michael >>> D Kinney >>> Sent: Friday, August 7, 2020 6:05 PM >>> To: devel@edk2.groups.io >>> Cc: Laszlo Ersek <ler...@redhat.com>; Andrew Fish <af...@apple.com>; >>> Leif Lindholm <l...@nuviainc.com> >>> Subject: [edk2-devel] [Wiki][Patch V2] Add EDK II Code First Process >>> Wiki Page >>> >>> 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 <ler...@redhat.com> >>> Cc: Andrew Fish <af...@apple.com> >>> Cc: Leif Lindholm <l...@nuviainc.com> >>> Signed-off-by: Michael D Kinney <michael.d.kin...@intel.com> >>> --- >>> 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 >>> +<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 | >>> +| --- | --- | --- | >>> +| `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 >>> >>> >>> >> >> >> > > IMPORTANT NOTICE: The contents of this email and any attachments are > confidential and may also be privileged. If you are not the intended > recipient, please notify the sender immediately and do not disclose the > contents to any other person, use it for any purpose, or store or copy the > information in any medium. Thank you. -=-=-=-=-=-=-=-=-=-=-=- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#63917): https://edk2.groups.io/g/devel/message/63917 Mute This Topic: https://groups.io/mt/76061237/21656 Group Owner: devel+ow...@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com] -=-=-=-=-=-=-=-=-=-=-=-
