From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from us-smtp-delivery-74.mimecast.com (us-smtp-delivery-74.mimecast.com [63.128.21.74]) by mx.groups.io with SMTP id smtpd.web12.13946.1585149649507054414 for ; Wed, 25 Mar 2020 08:20:49 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@redhat.com header.s=mimecast20190719 header.b=NWTn9OSl; spf=pass (domain: redhat.com, ip: 63.128.21.74, mailfrom: lersek@redhat.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1585149648; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=5yvRLDw30wlTSgDw5Gq4d7TjQWue7xMrluCgFr5+VpI=; b=NWTn9OSlcHtl5SB8bOtmrmlkYveKbNXHvBTY8eyjgztp7VmrFSXzVKGLE+tq8s0vz3eZ00 soP68suaUI+Y8G71dRit5QslqW5vb5peasOt96m4RzaN3sas2DsDkiOLp6fuseSELDtIaN 2pDUKiIRUuq4AT5EQ5tpeZgkP7TqQgw= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-236-cHwf_Wd0M7ujmMdc8uQNZg-1; Wed, 25 Mar 2020 11:20:38 -0400 X-MC-Unique: cHwf_Wd0M7ujmMdc8uQNZg-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 978531005510; Wed, 25 Mar 2020 15:20:36 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-113-153.ams2.redhat.com [10.36.113.153]) by smtp.corp.redhat.com (Postfix) with ESMTP id C4C6B5C1D4; Wed, 25 Mar 2020 15:20:34 +0000 (UTC) Subject: Re: [edk2-devel] [RFCv2] code-first process for UEFI-forum specifications To: devel@edk2.groups.io, leif@nuviainc.com, rfc@edk2.groups.io Cc: Felix Polyudov , Mark Doran , Andrew Fish , Michael D Kinney References: <20200323190548.GF22097@bivouac.eciton.net> From: "Laszlo Ersek" Message-ID: <09f7d5f4-fcf7-9c76-cc7d-7a2610e6b9f6@redhat.com> Date: Wed, 25 Mar 2020 16:20:33 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.9.1 MIME-Version: 1.0 In-Reply-To: <20200323190548.GF22097@bivouac.eciton.net> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Language: en-US Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit On 03/23/20 20:05, Leif Lindholm wrote: > Changes to v2 of this proposal: > - Feedback from Laszlo[a] and Mike[b] incorporated. > - I opted to view Mike's responses to Laszlo's questions as > accepted, as no follow-up was made. > > Feedback from Felix[c] *not* incorporated, as while I agree with all > of it, I am not convinced that information should go here, but should > instead reside with the UEFI Forum. (This text documents the public > part of the process - it would cause me slight impedance mismatch to > have it also document the non-public part.) > > [a] https://edk2.groups.io/g/devel/message/53422 > [b] https://edk2.groups.io/g/devel/message/53738 > [c] https://edk2.groups.io/g/devel/message/54453 > > / > Leif > > --- > > 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.org will have a product category each for > * 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, > in the Github flavour of markdown, in a file (or split across several files) > with .md suffix. > (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) > > Reference implementations targeting EDK2 will be held in branches on > edk2-staging. > Additional repositories for implementing reference features in > additional open source projects can be added in the future, as required. > > > ## 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. > > 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 multiple bugzilla entries must coexist on a single branch, > 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. But a tag in a > comment would be *highly* recommended. > > ### File names > New public header files need 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 codebase. > 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. > > | `typedef SOME_STRUCT` | `BZ1234_SOME_STRUCT` | Typedef only [2] | > | `StructField` | `Bz1234StructField` | In existing struct[3] | > | `typedef SOME_ENUM` | `BZ1234_SOME_ENUM` | Typedef only [2] | > > [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 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. Acked-by: Laszlo Ersek