[edk2-devel] [edk2-CCodingStandardsSpecification PATCH 1/1] Function example in Chapter 5 C Programming has extraneous semicolon

Wed Dec 9 16:40:41 UTC 2020

Hi Rebecca,

Reviewed-by: Michael D Kinney <michael.d.kinney at intel.com>

I see this was a GitHub issue entered in 2019.

We should be using TianoCore Bugzilla to enter specification issues.  I appreciate you
noticing this GitHub issue and generating a patch to get this fixed.

There are also recommendations for the Revision History to be updated for each change
with cross links between Revision History, git commit messages, and TianoCore Bugzilla.

    https://github.com/tianocore-docs/edk2-TemplateSpecification/wiki/TianoCore-Documents-Editing

There are some examples of this at the end of the Revision History of the EDK II Build Specification.  

Ideally, the Revision History contains a link to the TianoCore Bugzilla.  A few examples:

|            | [#465](https://bugzilla.tianocore.org/show_bug.cgi?id=465) DEC spec: document private definitions                       |           |

|            | [#1110](https://bugzilla.tianocore.org/show_bug.cgi?id=1110) Extend exclamation statement's keyword to case-insensitive |           |
|            | [#598](https://bugzilla.tianocore.org/show_bug.cgi?id=598) update supported operators in 8.2.4.6 Expressions            |           |
| 1.29       | [#1453](https://bugzilla.tianocore.org/show_bug.cgi?id=1453) Update Build spec to remove EDK related contents           | Mar 2019  |
| 1.30       | [#1952](https://bugzilla.tianocore.org/show_bug.cgi?id=1952) Update Build spec to support HOST_APPLICATION MODULE_TYPE  | July 2019 |

The TianoCore Bugzilla should be updated when the issue is Fixed/Resolved with links to the 
GitHub commits for the specification changes.

With this cross linking, when a specification is opened, the reader can review the Revision History,
follow the link to the TianoCore Bugzilla with a discussion of the specification change and see
the links to the final commits.  The reader can then follow the links to GitHub commits and see
the text changed rendered with by GitHub with green (add), red (delete), yellow (change) highlight 
when the "Display as rich diff" button is selected.

For example, BZ 465

	https://bugzilla.tianocore.org/show_bug.cgi?id=465

This BZ contains the full link to the GitHub commits:

	https://github.com/tianocore-docs/edk2-BuildSpecification/commit/afb505572de767fa05ca6348d36015faae387df9

If you clink on the "Display as rich diff" button, it will show a more readable version of the change:

	https://github.com/tianocore-docs/edk2-BuildSpecification/commit/afb505572de767fa05ca6348d36015faae387df9?short_path=3d47f51#diff-3d47f517e576e84d4c7bf02e39d31d597e39821a99fa4fbe08a91f6e03e56961

With the addition of the GitBook Action, you can also create a fork of a document in your personal
GitHub area and provide links to a branch with the proposed document changes that can be viewed 
using the "Display as rich diff" for easier/faster community review of document changed.  If you
enable the GitBook Action on your personal fork of a document, you can also provide links to the
published versions of the document with the proposed changes.

This full process makes sense for larger changes.  Does not seem to make sense for simple typos.

Thanks,

Mike

> -----Original Message-----
> From: Rebecca Cran <rebecca at nuviainc.com>
> Sent: Wednesday, December 9, 2020 7:16 AM
> To: devel at edk2.groups.io
> Cc: Rebecca Cran <rebecca at nuviainc.com>; Kinney, Michael D <michael.d.kinney at intel.com>; Leif Lindholm
> <leif at nuviainc.com>; Laszlo Ersek <lersek at redhat.com>; Andrew Fish <afish at apple.com>
> Subject: [edk2-CCodingStandardsSpecification PATCH 1/1] Function example in Chapter 5 C Programming has extraneous
> semicolon
> 
> https://github.com/tianocore-docs/edk2-CCodingStandardsSpecification/issues/1
> 
> "Section 5.7.1.10, there is a semicolon after the function paramters.
> Probably a copy-paste error from the header file."
> 
> Contributed-under: TianoCore Contribution Agreement 1.1
> Signed-off-by: Rebecca Cran <rebecca at nuviainc.com>
> ---
>  5_source_files/57_c_programming.md | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/5_source_files/57_c_programming.md b/5_source_files/57_c_programming.md
> index 8b9db584eea7..8b4111bfac29 100644
> --- a/5_source_files/57_c_programming.md
> +++ b/5_source_files/57_c_programming.md
> @@ -102,7 +102,7 @@ FooName (
>    IN UINTN      Arg2, OPTIONAL
>    OUT UINTN     *Arg3,
>    IN OUT UINTN  *Arg4
> -  );
> +  )
>  {
>    UINTN Local;
>    ...
> --
> 2.26.2

-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#68558): https://edk2.groups.io/g/devel/message/68558
Mute This Topic: https://groups.io/mt/78831194/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-