From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mga11.intel.com (mga11.intel.com [192.55.52.93]) by mx.groups.io with SMTP id smtpd.web12.697.1580844189749032694 for ; Tue, 04 Feb 2020 11:23:10 -0800 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: intel.com, ip: 192.55.52.93, mailfrom: michael.d.kinney@intel.com) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga006.jf.intel.com ([10.7.209.51]) by fmsmga102.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 04 Feb 2020 11:23:08 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.70,402,1574150400"; d="scan'208";a="235285578" Received: from orsmsx102.amr.corp.intel.com ([10.22.225.129]) by orsmga006.jf.intel.com with ESMTP; 04 Feb 2020 11:23:08 -0800 Received: from orsmsx121.amr.corp.intel.com (10.22.225.226) by ORSMSX102.amr.corp.intel.com (10.22.225.129) with Microsoft SMTP Server (TLS) id 14.3.439.0; Tue, 4 Feb 2020 11:23:07 -0800 Received: from orsmsx113.amr.corp.intel.com ([169.254.9.57]) by ORSMSX121.amr.corp.intel.com ([169.254.10.34]) with mapi id 14.03.0439.000; Tue, 4 Feb 2020 11:23:07 -0800 From: "Michael D Kinney" To: "devel@edk2.groups.io" , "lersek@redhat.com" , "rfc@edk2.groups.io" , "leif@nuviainc.com" , "Kinney, Michael D" Subject: Re: [edk2-devel] [edk2-rfc] [RFC] code-first process for UEFI-forum specifications Thread-Topic: [edk2-devel] [edk2-rfc] [RFC] code-first process for UEFI-forum specifications Thread-Index: AQHVz7LprcMEZQKeGkeEkwZYIKEh46f0aWoAgBcUmqA= Date: Tue, 4 Feb 2020 19:23:07 +0000 Message-ID: References: <20200120165852.GU15141@bivouac.eciton.net> In-Reply-To: Accept-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: dlp-product: dlpe-windows dlp-version: 11.2.0.6 dlp-reaction: no-action x-originating-ip: [10.22.254.138] MIME-Version: 1.0 Return-Path: michael.d.kinney@intel.com Content-Language: en-US Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Leif, A few comments included below. Thanks, Mike > -----Original Message----- > From: devel@edk2.groups.io On > Behalf Of Laszlo Ersek > Sent: Monday, January 20, 2020 10:42 AM > To: rfc@edk2.groups.io; leif@nuviainc.com; > devel@edk2.groups.io > Subject: Re: [edk2-devel] [edk2-rfc] [RFC] code-first > process for UEFI-forum specifications >=20 > On 01/20/20 17:58, Leif Lindholm wrote: > > This is a proposal for 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 goup 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 will enable this new process > by providing areas on > > https://bugzilla.tianocore.org/ to track both > specification updates and > > reference implementations and new repositories under > > https://github.com/tianocore/ dedicated to hold "code > first". > > > > > > ## Bugzilla > > > > bugzilla.tianocore.oorg will have a product category > each for >=20 > s/oorg/org/ >=20 > > * ACPI Specification > > * PI Specification > > * UEFI Specification > > > > Each product category will have a separate components > for > > * Specification > > * Reference implementation > > > > > > ## Github > > New repositories will be added for holding the text > changes and the source code. > > > > Specification text changes will be held within the > affected source repository. >=20 > This seems to require that the specifications be > available as something > "patchable" (e.g. GitBook source code), and offered in > some public git repo. >=20 I recommend we use MarkDown. GitHub flavored MarkDown may be a good choice so an ECR can be viewed from the web view of GitHub. This also support text based patch reviews of the ECR content. > > (This one may break down where we have a > specification change affecting multiple > > specifications, but at that point we can track it > with multiple BZ entries) > > > > Initially, edk2-spec-update will be created to hold > the reference > > implementations. Additional repositories for > implementing reference features in > > additional open source projects can be added in the > future, as required. I recommend using branches in the existing edk2-staging repository for changes that only impact EDK II firmware components/tools. > > > > > > ## Intended workflow > > The entity initiating a specifiation update raises a > Bugzilla in the appropriate > > area in bugzilla.tianocore.org. This entry contains > the outline of the change, > > and the full initial draft text is attached. >=20 > How does this play together with *patches* for specs > (see above)? > Attaching patches to BZs is not good practice. Should > we attach complete > renderings of the patched (huge) specs? >=20 > > > > 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 BZs have been created, new branches should > be created in the relevant > > repositories for each bugzilla - the branch names > should be BZ####, where #### > > describes the bugzilla ID assigned, optionally > followed by a '-' and something > > more descriptive. If multipls bugzilla entries must > coexist on a single branch, >=20 > s/multipls/multiple/ >=20 > > one of them is designated the 'top-level', with > dependencies properly tracked. > > That BZ will 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 need to be prefixed with the > relevant BZ####. > > > > [1] Modified in a non-backwards-compatible way. If, > for example, a statically > > sized array is grown - this does not need to be > prefixed. (Question: but a > > tag in a comment?) > > It would be good to clarify when the BZ### prefix is required and not required and to describe a few more use cases. Here=20 are a few. I am sure this list will be expanded when real examples are implemented. 1) New/modified interfaces require prefix. a) New structures. Only top level struct require a prefix. Fields and = sub structures do not. 2) New public header file names need prefix (e.g. Bz0001MyNewProtocol.h) 3) New GUID global variables need a prefix (e.g. gBz0001MyNewProtocolGuid) 4) Adding a field, enum, or #define to existing interface require a prefix 5) Internal interfaces and implementation elements do not need a prefix. > > The tagging must follow the coding style used by each > affected codebase. > > Examples: > > > > | Released in spec | Draft version in tree | Comment > | > > | --- | --- | --- > | > > | FunctionName | Bz1234FunctionName | EDK2 > | > > | function_name | bz1234_function_name | Linux > | > > | HEADER_MACRO | BZ1234_HEADER_MACRO | EDK2, > Linux | > > > > Alternative 1) > > Variable prefixes indicating global scope ('g' or > 'm') go before the BZ prefix. > > I prefer Alternative 1 to follow EDK II C Coding Standard. > > Alternative 2) > > Variable prefixes indicating global scope ('g' or > 'm') go after the BZ prefix. >=20 > Sounds good to me in general. >=20 > I think we'll have to work out the nuances of the > coding style in > practice, while actually developing such additions. I > can't name > anything specific that's missing from the proposal, but > I'm quite sure > we'll find corner cases in practice. >=20 > Thanks > Laszlo >=20 >=20 >=20