From: "Laszlo Ersek" <lersek@redhat.com>
To: devel@edk2.groups.io, leif@nuviainc.com, rfc@edk2.groups.io
Cc: Felix Polyudov <Felixp@ami.com>,
Mark Doran <mark.doran@intel.com>, Andrew Fish <afish@apple.com>,
Michael D Kinney <michael.d.kinney@intel.com>
Subject: Re: [edk2-devel] [RFCv2] code-first process for UEFI-forum specifications
Date: Wed, 25 Mar 2020 16:20:33 +0100 [thread overview]
Message-ID: <09f7d5f4-fcf7-9c76-cc7d-7a2610e6b9f6@redhat.com> (raw)
In-Reply-To: <20200323190548.GF22097@bivouac.eciton.net>
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 <lersek@redhat.com>
next prev parent reply other threads:[~2020-03-25 15:20 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-23 19:05 [RFCv2] code-first process for UEFI-forum specifications Leif Lindholm
2020-03-25 5:14 ` [edk2-rfc] " Ni, Ray
2020-05-12 15:29 ` Leif Lindholm
2020-03-25 15:20 ` Laszlo Ersek [this message]
2020-05-05 15:21 ` Samer El-Haj-Mahmoud
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-list from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=09f7d5f4-fcf7-9c76-cc7d-7a2610e6b9f6@redhat.com \
--to=devel@edk2.groups.io \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox