Re: [Patch V3 3/8] edk2: Remove commit message details from Contributions.txt

["Kinney, Michael D" <michael.d.kinney@intel.com>]

> -----Original Message-----
> From: Justen, Jordan L
> Sent: Monday, July 24, 2017 12:34 PM
> To: Kinney, Michael D <michael.d.kinney@intel.com>; Leif Lindholm
> <leif.lindholm@linaro.org>
> Cc: edk2-devel@lists.01.org; Andrew Fish <afish@apple.com>
> Subject: RE: [edk2] [Patch V3 3/8] edk2: Remove commit message
> details from Contributions.txt
> 
> On 2017-07-24 11:13:52, Kinney, Michael D wrote:
> > Hi Leif,
> >
> > I was attempting to keep the number of top level files to a
> minimum
> > and also attempt to use the same Contributions.txt file for
> both
> > source code repositories and document repositories.
> >
> > The set of files I am proposing be at the root of repositories
> are:
> >
> > * Readme.md
> > * License.txt
> > * Contributions.txt
> >
> > My first attempt at this was to move some of the commit message
> > details that are slightly different between source code and
> > documentation from Contributions.txt to the Readme.md and the
> > Readme.md also provides links to the wiki pages with even more
> > details.
> >
> > I am seeing feedback that there is a desire to retain the
> commit
> > message format details in Contributions.txt.  How about the
> following
> > approach for updates to Contributions.txt:
> >
> > 1) Update Contribution Agreement section from 1.0 to 1.1 to add
> >    support for TianoCore Documentation.
> >
> > 2) Update the 'Code Contributions' section to add the FreeBSD
> >    Documentation License as one of the accepted licenses for
> >    documentation.  Of course additional licenses can be
> considered
> >    at a later date if a community member requests to add
> documentation
> >    under a different license.
> >
> > 3) Update the 'Change Description / Commit Message / Patch
> Email'
> >    section so it applies equally well to both source code and
> >    documentation.  The following proposal provides guidelines
> that
> >    can work for patches to patches to edk2/master, other
> branches in
> >    edk2, other code repositories such as edk2-staging and edk2-
> non-osi,
> >    and document repositories in tianocore-docs.
> >
> 
> I understand why we might want to try to have a common
> Contributions.txt for consistency, but would there be an
> advantage to
> the separate ContributionAgreement.txt?
> 
> Would it allow us to change Contributions.txt more easily? (Less
> legal
> review?) If it were easier to change Contributions.txt, then
> would it
> be better to make them specific to the repo?
> 
> > ---- Begin ----
> >
> > =====================================================
> > = Change Description / Commit Message / Patch Email =
> > =====================================================
> >
> > Your change description should use the standard format for a
> > commit message, and must include your "Signed-off-by" signature
> > and the "Contributed-under" message.
> >
> > == Sample Change Description / Commit Message =
> >
> > === Start of sample patch email message ===
> >
> > From: Contributor Name <contributor@example.com>
> > Subject: [Repository/Branch PATCH] CodeModule: Brief-single-
> line-summary
> 
> It looks like this change will significantly increase the subject
> line
> length in the common case.
> 
> Could a [PATCH] email sent to edk2-devel be assumed to be for
> edk2/master? I think this is a good 'default' to have since it
> covers
> the majority of patches.

Yes.  See details below for when it is optional.

> 
> Another default could be to allow for Repository or Branch to be
> omited if there isn't a conflict. For example, UDK2017 should
> uniquely
> identify the edk2/UDK2017 even though it is just the branch name.
> Similarly, if a repository name is given without a branch, then
> the
> 'master' branch could be assumed.

Yes.  See details below for when it is optional.

> 
> This change should probably be sent as a separate patch to
> highlight
> it for discussion, right? (Unless [PATCH] could default to
> edk2/master, which would mean most people wouldn't have to change
> their process.)

Yes.  [PATCH] is default for edk2/master, so no change to current 
process at all for changes to area.  See details below.

> 
> -Jordan
> 
> >
> > Full-commit-message
> >
> > Contributed-under: TianoCore Contribution Agreement 1.1
> > Signed-off-by: Contributor Name <contributor@example.com>
> > ---
> >
> > An extra message for the patch email which will not be
> considered part
> > of the commit message can be added here.
> >
> > Patch content inline or attached
> >
> > === End of sample patch email message ===
> >
> > === Notes for sample patch email ===
> >
> > * The first line of commit message is taken from the email's
> subject
> >   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 ===
> >
> > * "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'.
> > * "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" 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.
> >
> > ---- End ----
> >
> > If this approach is acceptable, then I will update the patch
> series
> > to V4.
> >
> > Best regards,
> >
> > Mike
> >
> > > -----Original Message-----
> > > From: edk2-devel [mailto:edk2-devel-bounces@lists.01.org] On
> > > Behalf Of Leif Lindholm
> > > Sent: Friday, July 21, 2017 3:14 PM
> > > To: Justen, Jordan L <jordan.l.justen@intel.com>
> > > Cc: Kinney, Michael D <michael.d.kinney@intel.com>; edk2-
> > > devel@lists.01.org; Andrew Fish <afish@apple.com>
> > > Subject: Re: [edk2] [Patch V3 3/8] edk2: Remove commit
> message
> > > details from Contributions.txt
> > >
> > > On Fri, Jul 21, 2017 at 02:16:54PM -0700, Jordan Justen
> wrote:
> > > > On 2017-07-19 22:44:06, Michael D Kinney wrote:
> > > > > https://bugzilla.tianocore.org/show_bug.cgi?id=629
> > > > >
> > > > > Remove the change description, commit message, and
> > > > > patch email section from Contributions.txt.  This
> > > > > section is not part of the TianoCore Contribution
> > > > > Agreement.
> > > >
> > > > Neither are the ~35 remaining lines before this content,
> which
> > > you are
> > > > not removing.
> > > >
> > > > > The information is very important and is
> > > > > provided on the TianoCore web site and wiki and will
> > > > > be added to Readme.md in the root of the edk2
> > > > > repository.
> > > >
> > > > Yes. It is important for making contributions, as is the
> ~35
> > > lines
> > > > before the agreement that you didn't remove. So, why don't
> we
> > > just
> > > > keep them in Contributions.txt since they document how to
> make
> > > a
> > > > contribution?
> > > >
> > > > If you want a single file that only has the contribution
> > > agreement
> > > > text, then how about moving it to a
> ContributionAgreement.txt
> > > file,
> > > > and making Contributions.txt refer to it? I'm not sure why
> this
> > > would
> > > > be needed though.
> > >
> > > I think separating the mechanics of what a developer is
> supposed
> > > to do
> > > in order to contribute code from legalese of more interest to
> > > their
> > > legal department is a useful thing.
> > >
> > > This was why I was suggesting a SubmittingPatches.txt.
> Renaming
> > > Contributions.txt ContributionAgreement.txt would however
> > > indicate it
> > > contained only the contribution agreement, which (as you
> allude
> > > to) is
> > > not currently the case. The list of acceptable licenses would
> > > also
> > > need to move into the "howto" in this case.
> > >
> > > Regards,
> > >
> > > Leif
> > >
> > > > -Jordan
> > > >
> > > > >
> > > > > 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 | 49 ---------------------------------
> ----
> > > ------------
> > > > >  1 file changed, 49 deletions(-)
> > > > >
> > > > > diff --git a/Contributions.txt b/Contributions.txt
> > > > > index f87cbd73c6..06c60d8e17 100644
> > > > > --- a/Contributions.txt
> > > > > +++ b/Contributions.txt
> > > > > @@ -34,55 +34,6 @@ To make a contribution to a TianoCore
> > > project, follow these steps.
> > > > >     Contributions using other licenses might be accepted,
> but
> > > further
> > > > >     review will be required.
> > > > >
> > > > > -=====================================================
> > > > > -= Change Description / Commit Message / Patch Email =
> > > > > -=====================================================
> > > > > -
> > > > > -Your change description should use the standard format
> for a
> > > > > -commit message, and must include your "Signed-off-by"
> > > signature
> > > > > -and the "Contributed-under" message.
> > > > > -
> > > > > -== Sample Change Description / Commit Message =
> > > > > -
> > > > > -=== Start of sample patch email message ===
> > > > > -
> > > > > -From: Contributor Name <contributor@example.com>
> > > > > -Subject: [PATCH] CodeModule: Brief-single-line-summary
> > > > > -
> > > > > -Full-commit-message
> > > > > -
> > > > > -Contributed-under: TianoCore Contribution Agreement 1.0
> > > > > -Signed-off-by: Contributor Name
> <contributor@example.com>
> > > > > ----
> > > > > -
> > > > > -An extra message for the patch email which will not be
> > > considered part
> > > > > -of the commit message can be added here.
> > > > > -
> > > > > -Patch content inline or attached
> > > > > -
> > > > > -=== End of sample patch email message ===
> > > > > -
> > > > > -=== 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
> > > > > -  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.
> > > > > -* "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
> > > > > -  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 =
> > > > >  ========================================
> > > > > --
> > > > > 2.13.1.windows.2
> > > > >
> > > > > _______________________________________________
> > > > > edk2-devel mailing list
> > > > > edk2-devel@lists.01.org
> > > > > https://lists.01.org/mailman/listinfo/edk2-devel
> > > _______________________________________________
> > > edk2-devel mailing list
> > > edk2-devel@lists.01.org
> > > https://lists.01.org/mailman/listinfo/edk2-devel