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

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

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.

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.

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.)

-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