A presentation I gave to members of the Yocto Project team on how to most effectively get some of the work we're doing into upstream projects.

1. Contributing to Upstream Open Source Projects Best Practices for the Yocto Project Team Scott Garman <scott.a.garman@intel.com> http://yoctoproject.org February 15, 2011

2. Getting to the Point When submitting patches to upstream projects, the name of the game is making it as convenient as possible for the maintainers to accept and integrate your patch.

5. Add a feature (that the maintainer wants)?

6. Add a new test case to their test suite? The benefit of the patch should be articulated clearly and concisely.

8. Look for HACKING or README files in the source tree

9. Review project mailing list archives to find previous examples of patch submissions

10. Examples of Well-Organized Project Participation Guidelines OpenEmbedded: http://openembedded.org/index.php/How_to_submit_a_patch_to_OpenEmbedded GCC: http://gcc.gnu.org/contribute.html Mozilla: https://developer.mozilla.org/En/Developer_Guide/How_to_Submit_a_Patch GNOME: http://live.gnome.org/GnomeLove/SubmittingPatches

12. Submit a compressed patch using gzip or similar tools

13. Submit a patch without a clear explanation of what it does and why

14. Use language that could be interpreted as being critical of the project, its code, or its members * Possible exceptions may include critical security bugs or if the project's contribution instructions explicitly ask you to submit patches to individuals

16. Avoid trailing whitespace

17. Use the same format for commit logs (git-based projects tend to be especially strict about this)

18. Keep your commits atomic and logically separated

22. Testing your code shows not only that your patch doesn't break anything, but that you're disciplined enough to test your code as a matter of routine.

23. “ This patch has been tested on the Yocto Project's autobuilder and works for all of our architectures: x86/x86-64/arm/mips/ppc”

25. Keeping documentation up to date is one of the more challenging and thankless jobs a maintainer has to do

26. By including documentation patches, you will stand out above most other contributors as being detail-oriented and helpful

27. Dealing with Rejection Sometimes your patch will be rejected. It is important to make sure you understand whether the rejection is due to fundamental differences in philosophy, or whether the patch might be accepted if it were re-worked according to the preferences of the maintainer. If it's the former case, remain polite and accept it. Explain that we will continue to maintain the patch and are open to future collaboration.

28. The maintainer may want the patch re-worked to meet project requirements. This is acceptable, and the work should be done and the patch re-submitted. Remember, every patch we get upstream means we no longer have to maintain it . This saves us more work in the long run. It's also part of being a good citizen in open source communities! Dealing with Rejection

30. git format-patch -N (where N is the number of commits to include in the patchset)

31. Patch file(s) will be generated in the current directory. Use them as input to git send-email :

32. git send-email --to=upstream@devel-list <patchfile1> <patchfile2> …

33. man git-send-email for more details

35. You can create an account and use it when working on open source projects for free

36. GitHub allows you to clone repositories and submit pull requests via its web interface

37. Screencast tutorial here: http://teachmetocode.com/screencasts/getting-started-with-github/

38. Q&A I will also post this information on the Yocto Project wiki: http://wiki.yoctoproject.org