> -----Original Message----- > From: Justen, Jordan L > Sent: Monday, July 24, 2017 12:34 PM > To: Kinney, Michael D <[email protected]>; Leif Lindholm > <[email protected]> > Cc: [email protected]; Andrew Fish <[email protected]> > 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 <[email protected]> > > 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 <[email protected]> > > --- > > > > 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:[email protected]] On > > > Behalf Of Leif Lindholm > > > Sent: Friday, July 21, 2017 3:14 PM > > > To: Justen, Jordan L <[email protected]> > > > Cc: Kinney, Michael D <[email protected]>; edk2- > > > [email protected]; Andrew Fish <[email protected]> > > > 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 <[email protected]> > > > > > Cc: Andrew Fish <[email protected]> > > > > > Cc: Jordan Justen <[email protected]> > > > > > Contributed-under: TianoCore Contribution Agreement 1.1 > > > > > Signed-off-by: Michael D Kinney > <[email protected]> > > > > > --- > > > > > 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 <[email protected]> > > > > > -Subject: [PATCH] CodeModule: Brief-single-line-summary > > > > > - > > > > > -Full-commit-message > > > > > - > > > > > -Contributed-under: TianoCore Contribution Agreement 1.0 > > > > > -Signed-off-by: Contributor Name > <[email protected]> > > > > > ---- > > > > > - > > > > > -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 > > > > > [email protected] > > > > > https://lists.01.org/mailman/listinfo/edk2-devel > > > _______________________________________________ > > > edk2-devel mailing list > > > [email protected] > > > https://lists.01.org/mailman/listinfo/edk2-devel _______________________________________________ edk2-devel mailing list [email protected] https://lists.01.org/mailman/listinfo/edk2-devel
