On Sunday 11 October 2009, Øyvind Harboe wrote: > >> I've got some more complicated patches to come so pointers to how to > >> make patches that make your life easy are welcome. > > > > Start with "git diff"... > > > > It'd be nice if we could get to the point where patches sent > > to the mailing list can just be applied as-is with "git-am -s". > > > > That would require not just providing patches that can be > > applied without manual hacks (the $SUBJECT patch didn't seem > > to even try) ... but also adopting better discipline about > > patch comments. (No novels. Just "this changed; here's why.") > > I'm still learning git... I think that we should observe the git > knowledge level on this list and then consider if we can > write some instructions at the right level for the most > common operations w/openocd.
We can and should improve that knowledge level, IMO. :) For now I'll assume folk are aware of the GIT documentation and tutorials; there's a link to them on gitweb pages. It should be easier to reference some existing how-to docs than to write Yet Another Tutorial ... I was hoping that "git for SVN users" URL I referenced would help. My concern was more about patch content, and in this case the patch descriptive data. Good inputs to the system, in short; most users can live with "git clone" and "git pull", plus maybe "git diff" if they write patches. I think there's some overlap here with folk using git for work with Linux (== kernel) and U-Boot. I think all those skills should transfer directly; and there are writeups in those projects for "how 2 maek gud patches". Ones that come quickly to mind: http://userweb.kernel.org/~akpm/stuff/tpp.txt "The Perfect Patch" linux/Documentation/SubmittingPatches There's a good basic checklist in part 1, and information about the Signed-off-By stuff. In terms of "email-to-GIT" models, some points to remember (also mentioned in those two files): - $SUBJECT becomes the one-line patch summary, so have it be useful. "fix memleak <IN FOO>"; reference FOO! It's also used for tracking discussions about that particular patch (email etc) - One-line summaries aren't enough to explain patches. Make sure that folk browsing the repository history can make sense of the patch by including a useful summary of the patch too. Right now a "git log" is often not informative; let's fix that. (An "svn log" was pretty much unusable because of network issues; we can blame part of that on history.) Also, I'll suggest we adopt the audit trail model that includes "Signed-off-By" etc. Minimally, committers can use "git-am -s" to sign off on what they commit; that way we can know which maintainer was involved, not just who wrote the original bit. It's probably useful practice for submitters to include that too, the "Developer's Certificate of Origin 1.1" basically affirms that there are no known legal issues. Other bits -- acks, tested-by, cc, etc -- can be used when they're helpful. - Dave _______________________________________________ Openocd-development mailing list [email protected] https://lists.berlios.de/mailman/listinfo/openocd-development
