Re: [Patch v4 3/6] edk2: Update to TianoCore Contribution Agreement 1.1

[Jordan Justen <jordan.l.justen@intel.com>]

On 2017-07-26 10:45:41, Kinney, Michael D wrote:
> Hi Jordan,
> 
> Not sure I understand the 'whitespace' usage.

Previously I had given some examples of the style guide:

* whitespace: Change indentation to 5 spaces

* case: All functions must now use StUdLyCaPs

If it was instead:

* ch5: Change indentation to 5 spaces

* ch8: All functions must now use StUdLyCaPs

I don't think we are getting much value in adding the chapter number.
You'd have to go look up what chapter 5 and 8 are to get the context.
Also, what if a chapter is inserted or deleted? Then looking back
through the log may require even more investigation to determine the
context.

-Jordan

> 
> Can you provide some example subject lines for 
> documentation patches that I can add to the 
> tianocore-docs wiki?
> 
> Larger documents are broken up into directories in
> the document repository with a chapter number and/or
> chapter title in the directory name.  Very large
> documents may have multiple directory levels.
> 
> For smaller documents, the .md file are usually all
> in the root directory.
> 
> Thanks,
> 
> Mike
> 
> > -----Original Message-----
> > From: Justen, Jordan L
> > Sent: Wednesday, July 26, 2017 10:06 AM
> > To: Kinney, Michael D <michael.d.kinney@intel.com>; edk2-
> > devel@lists.01.org
> > Cc: Leif Lindholm <leif.lindholm@linaro.org>; Andrew Fish
> > <afish@apple.com>; Laszlo Ersek <lersek@redhat.com>
> > Subject: RE: [Patch v4 3/6] edk2: Update to TianoCore
> > Contribution Agreement 1.1
> > 
> > On 2017-07-25 10:55:45, Kinney, Michael D wrote:
> > > Hi Jordan,
> > >
> > > I also considered changing CodeModule to Module.  I will
> > > make that change.
> > >
> > > I like the idea of providing a chapter or section reference
> > > in a document patch when applicable.  I will update the
> > > tianocore-docs wiki with that recommendation as well.
> > 
> > This sounds good, except I don't think 'ch10' is as useful as
> > something like 'whitespace'.
> > 
> > -Jordan
> > 
> > >
> > > > -----Original Message-----
> > > > From: Justen, Jordan L
> > > > Sent: Tuesday, July 25, 2017 10:37 AM
> > > > To: Kinney, Michael D <michael.d.kinney@intel.com>; edk2-
> > > > devel@lists.01.org
> > > > Cc: Leif Lindholm <leif.lindholm@linaro.org>; Andrew Fish
> > > > <afish@apple.com>
> > > > Subject: Re: [Patch v4 3/6] edk2: Update to TianoCore
> > > > Contribution Agreement 1.1
> > > >
> > > > On 2017-07-24 16:45:13, Michael D Kinney wrote:
> > > > > https://bugzilla.tianocore.org/show_bug.cgi?id=629
> > > > >
> > > > > Update the TianoCore Contribution Agreement from Version
> > 1.0
> > > > > to Version 1.1 to cover open source documentation
> > associated
> > > > > with the TianoCore project.
> > > > >
> > > > > Version 1.0 covers source code files.  Version 1.1 is a
> > > > > backwards compatible extension that adds support for
> > document
> > > > > files in both source form and compiled form.
> > > > >
> > > > > The edk2 repository is updated so the same contribution
> > > > > agreement is used by developers that work on TianoCore
> > > > > related source code or TianoCore related documents.
> > > > >
> > > > > Links to RFC and Wiki on the GitBook documentation process
> > > > > * https://lists.01.org/pipermail/edk2-devel/2017-
> > > > March/008654.html
> > > > > * https://github.com/tianocore-docs/edk2-
> > > > TemplateSpecification/wiki
> > > > >
> > > > > Cc: Leif Lindholm <leif.lindholm@linaro.org>
> > > > > Cc: Andrew Fish <afish@apple.com>
> > > > > Cc: Jordan Justen <jordan.l.justen@intel.com>
> > > > > Contributed-under: TianoCore Contribution Agreement 1.1
> > > > > Signed-off-by: Michael D Kinney
> > <michael.d.kinney@intel.com>
> > > > > ---
> > > > >  Contributions.txt | 43 ++++++++++++++++++++++++++++++----
> > ----
> > > > -----
> > > > >  1 file changed, 30 insertions(+), 13 deletions(-)
> > > > >
> > > > > diff --git a/Contributions.txt b/Contributions.txt
> > > > > index f87cbd73c6..e52fd1adcc 100644
> > > > > --- a/Contributions.txt
> > > > > +++ b/Contributions.txt
> > > > > @@ -1,4 +1,3 @@
> > > > > -
> > > > >  ======================
> > > > >  = Code Contributions =
> > > > >  ======================
> > > > > @@ -12,7 +11,7 @@ To make a contribution to a TianoCore
> > > > project, follow these steps.
> > > > >     contribution is made under the terms of the specified
> > > > >     contribution agreement.  Your "Contributed-under"
> > message
> > > > >     must include the name of contribution agreement and
> > > > version.
> > > > > -   For example: Contributed-under: TianoCore Contribution
> > > > Agreement 1.0
> > > > > +   For example: Contributed-under: TianoCore Contribution
> > > > Agreement 1.1
> > > > >     The "TianoCore Contribution Agreement" is included
> > below
> > > > in
> > > > >     this document.
> > > > >  4. Submit your code to the TianoCore project using the
> > > > process
> > > > > @@ -28,6 +27,10 @@ To make a contribution to a TianoCore
> > > > project, follow these steps.
> > > > >     * Python-2.0: http://opensource.org/licenses/Python-
> > 2.0
> > > > >     * Zlib: http://opensource.org/licenses/Zlib
> > > > >
> > > > > +   For documentation:
> > > > > +   * FreeBSD Documentation License
> > > > > +     https://www.freebsd.org/copyright/freebsd-doc-
> > > > license.html
> > > > > +
> > > > >     Contributions of code put into the public domain can
> > also
> > > > be
> > > > >     accepted.
> > > > >
> > > > > @@ -47,11 +50,11 @@ and the "Contributed-under" message.
> > > > >  === Start of sample patch email message ===
> > > > >
> > > > >  From: Contributor Name <contributor@example.com>
> > > > > -Subject: [PATCH] CodeModule: Brief-single-line-summary
> > > > > +Subject: [Repository/Branch PATCH] CodeModule: Brief-
> > single-
> > > > line-summary
> > > > >
> > > > >  Full-commit-message
> > > > >
> > > > > -Contributed-under: TianoCore Contribution Agreement 1.0
> > > > > +Contributed-under: TianoCore Contribution Agreement 1.1
> > > > >  Signed-off-by: Contributor Name <contributor@example.com>
> > > > >  ---
> > > > >
> > > > > @@ -65,29 +68,37 @@ Patch content inline or attached
> > > > >  === Notes for sample patch email ===
> > > > >
> > > > >  * The first line of commit message is taken from the
> > email's
> > > > subject
> > > > > -  line following [PATCH]. The remaining portion of the
> > commit
> > > > message
> > > > > +  line following [Repository/Branch PATCH]. The remaining
> > > > portion of the commit message
> > > > >    is the email's content until the '---' line.
> > > > >  * git format-patch is one way to create this format
> > > > >
> > > > >  === Definitions for sample patch email ===
> > > > >
> > > > > -* "CodeModule" is a short idenfier for the affected code.
> > > > For
> > > > > -  example MdePkg, or MdeModulePkg UsbBusDxe.
> > > > > +* "Repository" is the identifier of the repository the
> > patch
> > > > applies.
> > > > > +  This identifier should only be provided for
> > repositories
> > > > other than
> > > > > +  'edk2'. For example 'edk2-BuildSpecification' or
> > 'staging'.
> > > > > +* "Branch" is the identifier of the branch the patch
> > applies.
> > > > This
> > > > > +  identifier should only be provided for branches other
> > than
> > > > 'edk2/master'.
> > > > > +  For example 'edk2/UDK2015', 'edk2-
> > > > BuildSpecification/release/1.27', or
> > > > > +  'staging/edk2-test'.
> > > > > +* "CodeModule" is a short identifier for the affected
> > code.
> > > > This identifier
> > > > > +  should not be provided for documentation patches. For
> > > > example 'MdePkg',
> > > > > +  or 'MdeModulePkg/UsbBusDxe'
> > > >
> > > > Maybe we could rename this from CodeModule to Module? I
> > think it
> > > > could
> > > > and should be use in documents where feasible.
> > > >
> > > > For example, in the style guide:
> > > >
> > > > * whitespace: Change involving whitespace style
> > > >
> > > > * case: Change involving word case style
> > > >
> > > > I think this should be applicable in all but the most
> > trivial
> > > > documents or code packages.
> > > >
> > > > I also had a comment on patch 6, but otherwise series:
> > > >
> > > > Reviewed-by: Jordan Justen <jordan.l.justen@intel.com>
> > > >
> > > > >  * "Brief-single-line-summary" is a short summary of the
> > > > change.
> > > > >  * The entire first line should be less than ~70
> > characters.
> > > > >  * "Full-commit-message" a verbose multiple line comment
> > > > describing
> > > > >    the change.  Each line should be less than ~70
> > characters.
> > > > > -* "Contributed-under" explicitely states that the
> > > > contribution is
> > > > > -  made under the terms of the contribtion agreement.
> > This
> > > > > +* "Contributed-under" explicitly states that the
> > contribution
> > > > is
> > > > > +  made under the terms of the contribution agreement.
> > This
> > > > >    agreement is included below in this document.
> > > > >  * "Signed-off-by" is the contributor's signature
> > identifying
> > > > them
> > > > >    by their real/legal name and their email address.
> > > > >
> > > > >  ========================================
> > > > > -= TianoCore Contribution Agreement 1.0 =
> > > > > += TianoCore Contribution Agreement 1.1 =
> > > > >  ========================================
> > > > >
> > > > > -INTEL CORPORATION ("INTEL") MAKES AVAILABLE SOFTWARE,
> > > > DOCUMENTATION,
> > > > > +INTEL CORPORATION ("INTEL") MAKES AVAILABLE SOFTWARE,
> > > > DOCUMENTATION ("DOCUMENTATION"),
> > > > >  INFORMATION AND/OR OTHER MATERIALS FOR USE IN THE
> > TIANOCORE
> > > > OPEN SOURCE
> > > > >  PROJECT (COLLECTIVELY "CONTENT"). USE OF THE CONTENT IS
> > > > GOVERNED BY THE
> > > > >  TERMS AND CONDITIONS OF THIS AGREEMENT BETWEEN YOU AND
> > INTEL
> > > > AND/OR THE
> > > > > @@ -100,14 +111,20 @@ AGREEMENT AND THE TERMS AND
> > CONDITIONS
> > > > OF ANY APPLICABLE LICENSE
> > > > >  AGREEMENTS OR NOTICES INDICATED OR REFERENCED BELOW, THEN
> > YOU
> > > > MAY NOT
> > > > >  USE THE CONTENT.
> > > > >
> > > > > -Unless otherwise indicated, all Content made available on
> > the
> > > > TianoCore
> > > > > +Unless otherwise indicated, all Content (except
> > > > Documentation) made available on the TianoCore
> > > > >  site is provided to you under the terms and conditions of
> > the
> > > > BSD
> > > > >  License ("BSD"). A copy of the BSD License is available
> > at
> > > > >  http://opensource.org/licenses/bsd-license.php
> > > > >  or when applicable, in the associated License.txt file.
> > > > >
> > > > > +Unless otherwise indicated, all Documentation made
> > available
> > > > on the
> > > > > +TianoCore site is provided to you under the terms and
> > > > conditions of the
> > > > > +FreeBSD Documentation License ("FreeBSD"). A copy of the
> > BSD
> > > > License is
> > > > > +available at https://www.freebsd.org/copyright/freebsd-
> > doc-
> > > > license.html or,
> > > > > +when applicable, in the associated License.txt file.
> > > > > +
> > > > >  Certain other content may be made available under other
> > > > licenses as
> > > > > -indicated in or with such Content. (For example, in a
> > > > License.txt file.)
> > > > > +indicated in or with such Content (for example, in a
> > > > License.txt file).
> > > > >
> > > > >  You accept and agree to the following terms and
> > conditions
> > > > for Your
> > > > >  present and future Contributions submitted to TianoCore
> > site.
> > > > Except
> > > > > --
> > > > > 2.13.1.windows.2
> > > > >