Contributing to Upstream Open Source Projects


Published on

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.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Contributing to Upstream Open Source Projects

  1. 1. Contributing to Upstream Open Source Projects Best Practices for the Yocto Project Team Scott Garman <> February 15, 2011
  2. 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.
  3. 3. Do Your Homework <ul><li>How is this patch relevant to the upstream project?
  4. 4. Does it: </li><ul><li>Fix a bug?
  5. 5. Add a feature (that the maintainer wants)?
  6. 6. Add a new test case to their test suite? </li></ul></ul>The benefit of the patch should be articulated clearly and concisely.
  7. 7. Research How Upstream Projects Accept Patches <ul><li>Search for documented processes on the project's web site (search for “get[ting] involved”, “submit patch”, “developer guide”)
  8. 8. Look for HACKING or README files in the source tree
  9. 9. Review project mailing list archives to find previous examples of patch submissions </li></ul>
  10. 10. Examples of Well-Organized Project Participation Guidelines OpenEmbedded: GCC: Mozilla: GNOME:
  11. 11. What NOT To Do <ul><li>Submit the patch privately directly to the maintainer *
  12. 12. Submit a compressed patch using gzip or similar tools
  13. 13. Submit a patch without a clear explanation of what it does and why
  14. 14. Use language that could be interpreted as being critical of the project, its code, or its members </li></ul>* Possible exceptions may include critical security bugs or if the project's contribution instructions explicitly ask you to submit patches to individuals
  15. 15. Making Your Patch a Slam-dunk: Follow the project's coding style <ul><li>Use the same whitespace style (tabs vs. spaces) that the surrounding code uses
  16. 16. Avoid trailing whitespace
  17. 17. Use the same format for commit logs (git-based projects tend to be especially strict about this)
  18. 18. Keep your commits atomic and logically separated </li></ul>
  19. 19. Making Your Patch a Slam-dunk: Tie it to a bug number <ul><li>Find the project's bugtracker </li><ul><li>Search for the bug
  20. 20. If it doesn't exist, file a new bug </li></ul><li>Some projects, e.g. Mozilla, do not accept any code unless it is associated with a bug filed in Bugzilla </li></ul>
  21. 21. Making Your Patch a Slam-dunk: Mention how it has been tested <ul><li>From the maintainer's perspective, it is natural to be cautious when accepting patches from new contributors who may not know the codebase well.
  22. 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. 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” </li></ul>
  24. 24. Making Your Patch a Slam-dunk: Include documentation patches <ul><li>This is more true for feature additions than bugfixes
  25. 25. Keeping documentation up to date is one of the more challenging and thankless jobs a maintainer has to do
  26. 26. By including documentation patches, you will stand out above most other contributors as being detail-oriented and helpful </li></ul>
  27. 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. 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
  29. 29. Common Patch Submission Workflow with Git <ul><li>Clone the upstream git repo, make changes in your own branch and commit them
  30. 30. git format-patch -N (where N is the number of commits to include in the patchset)
  31. 31. Patch file(s) will be generated in the current directory. Use them as input to git send-email :
  32. 32. git send-email --to=upstream@devel-list <patchfile1> <patchfile2> …
  33. 33. man git-send-email for more details </li></ul>
  34. 34. GitHub Workflow <ul><li>GitHub is a popular host for some upstream projects
  35. 35. You can create an account and use it when working on open source projects for free
  36. 36. GitHub allows you to clone repositories and submit pull requests via its web interface
  37. 37. Screencast tutorial here: </li></ul>
  38. 38. Q&A I will also post this information on the Yocto Project wiki: