From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from EUR05-VI1-obe.outbound.protection.outlook.com (EUR05-VI1-obe.outbound.protection.outlook.com [40.107.21.42]) by mx.groups.io with SMTP id smtpd.web11.13566.1591936785238374803 for ; Thu, 11 Jun 2020 21:39:46 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@armh.onmicrosoft.com header.s=selector2-armh-onmicrosoft-com header.b=ILpnKwUr; spf=pass (domain: arm.com, ip: 40.107.21.42, mailfrom: samer.el-haj-mahmoud@arm.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=+AM+bRlsPot6KR6dSqijo6iRMqyx3x57mCsVNDt3lDI=; b=ILpnKwUr+5FDQnyfvR/9io245n9f02zqrxRwL37dU+6tKmlLwzYFK6WBInwaFBP5vmleIq6aw2cx2AJx4NcDIIrsPJQD2/fuve5aBFufJpvXgkJuDqIQMlodpVC9x3QDQDTMty0KxBsZP7N8pg0B/bICEejV5CtWYaW5dSPT+JY= Received: from DB7PR02CA0007.eurprd02.prod.outlook.com (2603:10a6:10:52::20) by DB6PR0801MB1832.eurprd08.prod.outlook.com (2603:10a6:4:3c::14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3088.18; Fri, 12 Jun 2020 04:39:42 +0000 Received: from DB5EUR03FT052.eop-EUR03.prod.protection.outlook.com (2603:10a6:10:52:cafe::d2) by DB7PR02CA0007.outlook.office365.com (2603:10a6:10:52::20) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3088.19 via Frontend Transport; Fri, 12 Jun 2020 04:39:42 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 63.35.35.123) smtp.mailfrom=arm.com; edk2.groups.io; dkim=pass (signature was verified) header.d=armh.onmicrosoft.com;edk2.groups.io; dmarc=bestguesspass action=none header.from=arm.com; Received-SPF: Pass (protection.outlook.com: domain of arm.com designates 63.35.35.123 as permitted sender) receiver=protection.outlook.com; client-ip=63.35.35.123; helo=64aa7808-outbound-1.mta.getcheckrecipient.com; Received: from 64aa7808-outbound-1.mta.getcheckrecipient.com (63.35.35.123) by DB5EUR03FT052.mail.protection.outlook.com (10.152.21.82) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3088.18 via Frontend Transport; Fri, 12 Jun 2020 04:39:42 +0000 Received: ("Tessian outbound 4f5776643448:v59"); Fri, 12 Jun 2020 04:39:42 +0000 X-CR-MTA-TID: 64aa7808 Received: from bc66ad0c491f.2 by 64aa7808-outbound-1.mta.getcheckrecipient.com id F203BD9D-50A6-4377-9D01-E29E1446BB71.1; Fri, 12 Jun 2020 04:39:37 +0000 Received: from EUR05-VI1-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id bc66ad0c491f.2 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Fri, 12 Jun 2020 04:39:37 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=EA1J22xF71DFqtTndrYO7WWfQlsuX4EEKtWuDFSeXoPW1IQsV6VHENnSzlEh0T+XR9rzLuLp6M5ZGYfpgh/P30QPrP97wsC9iumcWY2jQXfzvfQHuHnfLgZbYirX7+QYrRY5/XthEbT9n+7YFWeSD11KKVzy5hg5RgAAUDKjhvA3y03y30fwInoMJC4OxCTzx3wRbddhX2hSF0+LkCWjs5ZQ0sm7zMmX3BCA45qK9PP7JA/Z5qiXR8zj27ZIEOxskmXX6WG07ZTWGKqqUnn0sjyBlpA14QxuyG2+UJ6otaU9aFXLvTs5g1D/ljCPtukme1onV+Me5dvfmLLnxgY2Rg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=+AM+bRlsPot6KR6dSqijo6iRMqyx3x57mCsVNDt3lDI=; b=ARM/LKIPdhjebT82JNDHsqEOe2x6pM77eFwDMUESDfetYIDwpzfdIXisGYnmpVDVl5Rx/KwhTVQy/08WBy6NsHlu9c7J1mNvLqvaQyUlwbzPxFdKshRbGvO1OejwXBaic6mtY5rj/HHVoE0KnSr/sqvLkgMl95w7Gstb/MLPvhxzLJ9xU+2UHFW+KecqlcWQPkt4pXZf67wsa5veSf4OBBessHMlDDs5eE6XiGJfGZ6+581w+ai1hWhPTW5yFlecyPIvPlH79bBnKB5f6o/CKCB4VatS87ZDs2xLGXKfkd8qMsF33UOoqR6Y7varxoJTLdAqiJALDodQ+/lFVrxSxQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=arm.com; dmarc=pass action=none header.from=arm.com; dkim=pass header.d=arm.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=+AM+bRlsPot6KR6dSqijo6iRMqyx3x57mCsVNDt3lDI=; b=ILpnKwUr+5FDQnyfvR/9io245n9f02zqrxRwL37dU+6tKmlLwzYFK6WBInwaFBP5vmleIq6aw2cx2AJx4NcDIIrsPJQD2/fuve5aBFufJpvXgkJuDqIQMlodpVC9x3QDQDTMty0KxBsZP7N8pg0B/bICEejV5CtWYaW5dSPT+JY= Received: from DB7PR08MB3260.eurprd08.prod.outlook.com (2603:10a6:5:21::23) by DB7PR08MB3882.eurprd08.prod.outlook.com (2603:10a6:10:7d::26) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3066.18; Fri, 12 Jun 2020 04:39:34 +0000 Received: from DB7PR08MB3260.eurprd08.prod.outlook.com ([fe80::88ec:d703:3e32:4c6b]) by DB7PR08MB3260.eurprd08.prod.outlook.com ([fe80::88ec:d703:3e32:4c6b%5]) with mapi id 15.20.3088.019; Fri, 12 Jun 2020 04:39:34 +0000 From: "Samer El-Haj-Mahmoud" To: "devel@edk2.groups.io" , "rfc@edk2.groups.io" , "ray.ni@intel.com" , "leif@nuviainc.com" CC: "Felixp@ami.com" , "Doran, Mark" , Andrew Fish , Laszlo Ersek , "Kinney, Michael D" , Dong Wei , Samer El-Haj-Mahmoud Subject: Re: [edk2-devel] [edk2-rfc] [RFCv2] code-first process for UEFI-forum specifications Thread-Topic: [edk2-devel] [edk2-rfc] [RFCv2] code-first process for UEFI-forum specifications Thread-Index: AdYp7wte1clxxO15QnuNQF4AmoltLwEoMOlABHjiOiA= Date: Fri, 12 Jun 2020 04:39:34 +0000 Message-ID: References: <160F0156FEDC6091.6323@groups.io> <1610B54128789A26.14697@groups.io> In-Reply-To: <1610B54128789A26.14697@groups.io> Accept-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-ts-tracking-id: d820b49a-9a91-477e-8bd9-db1dce1bac2d.1 x-checkrecipientchecked: true Authentication-Results-Original: edk2.groups.io; dkim=none (message not signed) header.d=none;edk2.groups.io; dmarc=none action=none header.from=arm.com; x-originating-ip: [99.132.126.10] x-ms-publictraffictype: Email X-MS-Office365-Filtering-HT: Tenant X-MS-Office365-Filtering-Correlation-Id: 177f2355-aabb-4ecb-d3b5-08d80e8a9fdf x-ms-traffictypediagnostic: DB7PR08MB3882:|DB6PR0801MB1832: x-ld-processed: f34e5979-57d9-4aaa-ad4d-b122a662184d,ExtAddr x-ms-exchange-transport-forked: True X-Microsoft-Antispam-PRVS: x-checkrecipientrouted: true nodisclaimer: true x-ms-oob-tlc-oobclassifiers: OLM:10000;OLM:10000; x-forefront-prvs: 0432A04947 X-MS-Exchange-SenderADCheck: 1 X-Microsoft-Antispam-Untrusted: BCL:0; X-Microsoft-Antispam-Message-Info-Original: dfTbHvgPXLdcngDcLo4LyAR8eJQbXQiyeTIjLQJCaZSWAprz8gL0McUdeuJRWrFlsuc9yI8cv/TGsiPXUurm//u7ZkSUOnh/REtEf172yhJ5Ub2dUNPKEKkeiYpGUR37QPIXLsSReuFh9IzjoLv43VjVblq12MhgFZlRP2buyY3/rUQajhrDNc8a8fXwuhuiNrOQrhak8FQpbwfcD0rDZn/UEB14Q8K8wHDSDvZBJP5lAF4RIs7qE6uiA3W6nBFJsGXKbkQSpSuaIbOWrEz/cOSZpSa8wb+TW7r1LLMOjSSQeemfprnwQCV6Ijb7pMXo/YAWIWyDMqv6y+fSiHyw/2vlp/xlABj1V+J53dAihOhJ3UJHef45k0QZU11PI/UxJHumS4zqYF0OaYf8TfrpIA== X-Forefront-Antispam-Report-Untrusted: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:DB7PR08MB3260.eurprd08.prod.outlook.com;PTR:;CAT:NONE;SFTY:;SFS:(4636009)(366004)(136003)(39860400002)(376002)(346002)(396003)(186003)(6506007)(8936002)(2906002)(26005)(316002)(71200400001)(8676002)(53546011)(86362001)(4326008)(9686003)(64756008)(55016002)(66556008)(66946007)(54906003)(83380400001)(7696005)(110136005)(52536014)(76116006)(66476007)(33656002)(478600001)(66446008)(5660300002)(966005);DIR:OUT;SFP:1101; x-ms-exchange-antispam-messagedata: bH9kiTLX6CtVXY7hdcA0qE/xnwHDnl1+Ew3Hgkec83tnYhn2zwKEYnONpcDKSeHH/jLB82BZ16Ogq25FuNJq3HxGBaxEGjg999v/RP84eib8BWL1L2iTXOhgFU9T6d/pZpIV0qA6nX8kCPah4yYvaHQqdt3VmEzQ3RXnhItiXveTPDZmyHA7oczRcwqBoqw3KqZ9pMAU1buTqRU5FXHbW3sSbv+DmA6fx1m1PxHgXsI7jI8dmTatjzLnIl7U03bYdxWOVPYeoAwdBMe1M5qUuMolDY/dgmAptuS87wFUyXCEHZh7C2hqk1igHLXjLdghWk6baZFI+pngF37mnHe/7o/WBc4xaJxRqtoyoToChpLx3RVKHm2oF9YdLSF3GoyBL/+ZlqmceMlYzTyx4qKYexhBUiVI+iFUTBNPoJNgJOlUSksPMZWmrOq3p+hdBUjV9lTQ3zglKWmEg4xJgBLr3DRYYQsaX6aCrzI8n0gTKGOFWS2c4cerEXUB5S/Bv54d MIME-Version: 1.0 X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB7PR08MB3882 Original-Authentication-Results: edk2.groups.io; dkim=none (message not signed) header.d=none;edk2.groups.io; dmarc=none action=none header.from=arm.com; Return-Path: Samer.El-Haj-Mahmoud@arm.com X-EOPAttributedMessage: 0 X-MS-Exchange-Transport-CrossTenantHeadersStripped: DB5EUR03FT052.eop-EUR03.prod.protection.outlook.com X-Forefront-Antispam-Report: CIP:63.35.35.123;CTRY:IE;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:64aa7808-outbound-1.mta.getcheckrecipient.com;PTR:ec2-63-35-35-123.eu-west-1.compute.amazonaws.com;CAT:NONE;SFTY:;SFS:(4636009)(396003)(346002)(136003)(39860400002)(376002)(46966005)(2906002)(5660300002)(8936002)(186003)(55016002)(53546011)(86362001)(54906003)(4326008)(316002)(26005)(9686003)(966005)(336012)(478600001)(356005)(82740400003)(47076004)(450100002)(82310400002)(33656002)(110136005)(7696005)(8676002)(83380400001)(52536014)(81166007)(70586007)(6506007)(70206006);DIR:OUT;SFP:1101; X-MS-Office365-Filtering-Correlation-Id-Prvs: 9d083b78-11d1-41e7-991d-08d80e8a9b42 X-Forefront-PRVS: 0432A04947 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 6xfxmdnYKS9NgnOIsY9LOUXYcO7FBeXCKeRloWD+orIUFiyKPCY2noH4o9iYJXkXurJkYJp2KyWywz5/wTXot1BkDZ+8USiAo5W/mjbM9igQg+B3EsQnxgg1iveZK2/pZZR/ALTbRMgm8GVvqbRCWEoPZsriWBsihCyguDsiRXrGu7qD8WAAzy/ehfWC7vtlSHmqgtT1p5dj/slUK/P4Yig4ggelrOpHFP8fJNKrwWlfp/B6hIhK4jL5fUTRT5q+r7otu0n4jBHcwazdvDbFD3v5EthRl9s3TcxJ9dnAxvZ0npjM+QvzKLJBJ45ratsWLf9n0i5/5kDa1XtW+vucSj7qNnW+XtK9WXQmK81hE/0ng0ossUEc48z4A6e+y72s1izu0qM47Yqz9Iw9yUCEevbndPJ5sux/b829kbek+pXYgVSzvozRf2sv0qMdXNv+BB6+TeK7m7CKf74ba7yRVGF/NzfrHfWGKyICYQ0KgLM= X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 12 Jun 2020 04:39:42.3197 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 177f2355-aabb-4ecb-d3b5-08d80e8a9fdf X-MS-Exchange-CrossTenant-Id: f34e5979-57d9-4aaa-ad4d-b122a662184d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=f34e5979-57d9-4aaa-ad4d-b122a662184d;Ip=[63.35.35.123];Helo=[64aa7808-outbound-1.mta.getcheckrecipient.com] X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB6PR0801MB1832 Content-Language: en-US Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Leif, I received additional feedback on this proposal. We should add the UEFI Shell Specification to this new process. This inclu= des adding a bugzilla.tianocore.org product category and a new Github repos= itory for the "UEFI Shell Specification". Thanks, --Samer > -----Original Message----- > From: devel@edk2.groups.io On Behalf Of Samer El- > Haj-Mahmoud via groups.io > Sent: Wednesday, May 20, 2020 6:19 AM > To: rfc@edk2.groups.io; Samer El-Haj-Mahmoud Mahmoud@arm.com>; ray.ni@intel.com; leif@nuviainc.com; > devel@edk2.groups.io > Cc: Felixp@ami.com; Doran, Mark ; Andrew Fish > ; Laszlo Ersek ; Kinney, Michael D > ; Samer El-Haj-Mahmoud Mahmoud@arm.com> > Subject: Re: [edk2-devel] [edk2-rfc] [RFCv2] code-first process for UEFI= -forum > specifications > > Are there any additional comments on the code first process for UEFI > specifications? > > When should we expect the process to *actually* start being used? > > Thanks, > --Samer > > > -----Original Message----- > > From: rfc@edk2.groups.io On Behalf Of Samer > > El-Haj- Mahmoud via groups.io > > Sent: Thursday, May 14, 2020 5:11 PM > > To: rfc@edk2.groups.io; ray.ni@intel.com; leif@nuviainc.com; > > devel@edk2.groups.io > > Cc: Felixp@ami.com; Doran, Mark ; Andrew Fish > > ; Laszlo Ersek ; Kinney, Michael D > > ; Samer El-Haj-Mahmoud > Mahmoud@arm.com> > > Subject: Re: [edk2-rfc] [RFCv2] code-first process for UEFI-forum > > specifications > > > > Leif, Ray, > > > > I have not seen any discussion on this thread since March(!)... > > > > Please see my comments below. > > > > > > > -----Original Message----- > > > From: rfc@edk2.groups.io On Behalf Of Ni, Ray > > > via Groups.Io > > > Sent: Wednesday, March 25, 2020 1:15 AM > > > To: rfc@edk2.groups.io; leif@nuviainc.com; devel@edk2.groups.io > > > Cc: Felixp@ami.com; Doran, Mark ; Andrew Fish > > > ; Laszlo Ersek ; Kinney, Michael > > > D > > > Subject: Re: [edk2-rfc] [RFCv2] code-first process for UEFI-forum > > > specifications > > > > > > > > > > > ## 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, in the Github flavour of markdown, in a file (or split > > > > across several files) 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 multiple specifications, but at that point we can track > > > > it with multiple BZ entries) > > > > > > > > > > > > > > > ## 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. But > > > > a tag in a comment would be *highly* recommended. > > > > > > If a protocol is enhanced to provide more interfaces with increased > > > revision 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. > > > > > > > I think pre-fixing the new interfaces is sufficient. Otherwise, you > > need to modify all code using the existing interfaces (for build > > verification) > > > > > > > But the protocol definition is changed, it also needs to be prefixed > > > according to this flow. > > > Can you clarify a bit more? > > > > > > > A changed protocol definition is not backwards compatible, and > > typically results in a new protocol GUID. In that case, it really > > becomes a new definition and need to be pre-fixed per this rule. Right= ? > > > > > > > > > > ### File names > > > > New public header files need the prefix. I.e. > > > > `Bz1234MyNewProtocol.h` Private header files do not need the prefi= x. > > > > > > > > ### Contents > > > > > > > > The tagging must follow the coding style used by each affected cod= ebase. > > > > Examples: > > > > > > > > | 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 don't think they require the prefix. Do you agree? > > > > > > > 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. > > > > > > > > | `typedef SOME_STRUCT` | `BZ1234_SOME_STRUCT` | Typedef on= ly > > > [2] | > > > > | `StructField` | `Bz1234StructField` | In existin= g struct[3] | > > > > | `typedef SOME_ENUM` | `BZ1234_SOME_ENUM` | Typedef on= ly > > > [2] | > > > > > > > > [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 prefix"? > > > If yes, then I think macros defined in BzXXX.h also don't need the p= refix. > > > > > > > [3] Individual fields in newly added typedefd struct do not need > > > > prefix, > > the > > > > struct already carried the prefix. > > > > > > > > Variable prefixes indicating global scope ('g' or 'm') go before > > > > the BZ > > prefix. > > > > > > > > | `gSomeGuid` | `gBz1234SomeGuid` | = | > > > > > > > > Local identifiers, including module-global ones (m-prefixed) do > > > > not require a BZ prefix. > > > > > > I think only the names (struct type name, enum type name, interface > > > name, protocol/ppi name) defined in public header files need the BZ > > > prefix when the public header doesn't have prefix. > > > Right? > > > > > > > The way I read it, *all* new (and non-backward modified) identifiers > > (typedef struct, typedef enum, and new structfield in existing struct) > > need to be pre-fixed, regardless if the filename is prefixed or not. > > Correct? > > > > > > > > > > > > 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. > > > > > > IMPORTANT NOTICE: The contents of this email and any attachments are > confidential and may also be privileged. If you are not the intended rec= ipient, > 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 i= n any > medium. Thank you. > >=20 IMPORTANT NOTICE: The contents of this email and any attachments are confi= dential and may also be privileged. If you are not the intended recipient, = please notify the sender immediately and do not disclose the contents to an= y other person, use it for any purpose, or store or copy the information in= any medium. Thank you.