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 <ler...@redhat.com> -=-=-=-=-=-=-=-=-=-=-=- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#56299): https://edk2.groups.io/g/devel/message/56299 Mute This Topic: https://groups.io/mt/72500372/21656 Group Owner: devel+ow...@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com] -=-=-=-=-=-=-=-=-=-=-=-
