From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by mx.groups.io with SMTP id smtpd.web12.6011.1585113304164731928 for ; Tue, 24 Mar 2020 22:15:04 -0700 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: intel.com, ip: 134.134.136.20, mailfrom: ray.ni@intel.com) IronPort-SDR: Ok5cteBvuyTv4axXaDVMWeonB01Zf3kiNzXa+aQYkQx0NzGJEJbduFxl38gpk83S2cGTc4qS1t nF1kv92HaK0w== X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by orsmga101.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 24 Mar 2020 22:15:03 -0700 IronPort-SDR: wU2v4AerGY+ke0inuIVtOKBU3cezDDV3rcpXLFWHDxiuk3XbCWcryHVbNFarzK8np9ZWjDbb+e Oh1MuzM6zkag== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.72,303,1580803200"; d="scan'208";a="446510213" Received: from fmsmsx103.amr.corp.intel.com ([10.18.124.201]) by fmsmga005.fm.intel.com with ESMTP; 24 Mar 2020 22:15:02 -0700 Received: from FMSMSX110.amr.corp.intel.com (10.18.116.10) by FMSMSX103.amr.corp.intel.com (10.18.124.201) with Microsoft SMTP Server (TLS) id 14.3.439.0; Tue, 24 Mar 2020 22:15:02 -0700 Received: from shsmsx107.ccr.corp.intel.com (10.239.4.96) by fmsmsx110.amr.corp.intel.com (10.18.116.10) with Microsoft SMTP Server (TLS) id 14.3.439.0; Tue, 24 Mar 2020 22:15:01 -0700 Received: from shsmsx104.ccr.corp.intel.com ([169.254.5.206]) by SHSMSX107.ccr.corp.intel.com ([169.254.9.232]) with mapi id 14.03.0439.000; Wed, 25 Mar 2020 13:14:59 +0800 From: "Ni, Ray" To: "rfc@edk2.groups.io" , "leif@nuviainc.com" , "devel@edk2.groups.io" CC: Felix Polyudov , "Doran, Mark" , Andrew Fish , Laszlo Ersek , "Kinney, Michael D" Subject: Re: [edk2-rfc] [RFCv2] code-first process for UEFI-forum specifications Thread-Topic: [edk2-rfc] [RFCv2] code-first process for UEFI-forum specifications Thread-Index: AQHWAUYXyVOG151Kpku5wpAnGSkHNqhYv+Kw Date: Wed, 25 Mar 2020 05:14:59 +0000 Message-ID: <734D49CCEBEEF84792F5B80ED585239D5C4B2676@SHSMSX104.ccr.corp.intel.com> References: <20200323190548.GF22097@bivouac.eciton.net> In-Reply-To: <20200323190548.GF22097@bivouac.eciton.net> Accept-Language: en-US, zh-CN 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.239.127.40] MIME-Version: 1.0 Return-Path: ray.ni@intel.com Content-Language: en-US Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable >=20 > ## Github > New repositories will be added for holding the text changes and the sourc= e code. >=20 > Specification text changes will be held within the affected source reposi= tory, > in the Github flavour of markdown, in a file (or split across several fil= es) > with .md suffix. What's the case when multiple .MD files are needed? > (This one may break down where we have a specification change affecting m= ultiple > specifications, but at that point we can track it with multiple BZ entrie= s) >=20 >=20 > ## 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####. >=20 > [1] Modified in a non-backwards-compatible way. If, for example, a static= ally > sized array is grown - this does not need to be prefixed. But a tag i= n a > comment would be *highly* recommended. If a protocol is enhanced to provide more interfaces with increased revisio= n number, would you like the protocol name to be prefixed with BZ####? Or just the new interfaces added to the protocol are prefixed the BZ####? I think just prefixing the new interfaces can meet the purpose. But the protocol definition is changed, it also needs to be prefixed accord= ing to this flow. Can you clarify a bit more? >=20 > ### File names > New public header files need the prefix. I.e. `Bz1234MyNewProtocol.h` > Private header files do not need the prefix. >=20 > ### Contents >=20 > The tagging must follow the coding style used by each affected codebase. > Examples: >=20 > | Released in spec | Draft version in tree | Comment = | > | --- | --- | --- = | > | `FunctionName` | `Bz1234FunctionName` | = | > | `HEADER_MACRO` | `BZ1234_HEADER_MACRO` | = | If FunctionName or HEADER_MACRO is defined in non-public header files, I do= n't think they require the prefix. Do you agree? =20 > 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 existi= ng > struct requires no prefix. >=20 > | `typedef SOME_STRUCT` | `BZ1234_SOME_STRUCT` | Typedef only [2] = | > | `StructField` | `Bz1234StructField` | In existing struc= t[3] | > | `typedef SOME_ENUM` | `BZ1234_SOME_ENUM` | Typedef only [2] = | >=20 > [2] If the struct or enum definition is separate from the typedef in the = public > header, the definition does not need the prefix. What does "separate" mean? Does it mean "struct or enum in the public header BzXXX.h don't need the pr= efix"? If yes, then I think macros defined in BzXXX.h also don't need the prefix. > [3] Individual fields in newly added typedefd struct do not need prefix, = the > struct already carried the prefix. >=20 > Variable prefixes indicating global scope ('g' or 'm') go before the BZ p= refix. >=20 > | `gSomeGuid` | `gBz1234SomeGuid` | = | >=20 > Local identifiers, including module-global ones (m-prefixed) do not requi= re a > BZ prefix. I think only the names (struct type name, enum type name, interface name, p= rotocol/ppi name) defined in public header files need the BZ prefix when the public header do= esn't have prefix. Right?