If you are new to the Xen community and want to know how the development process works -- and in particular, if you want to know how you can get your changes in -- this talk is for you. My goal is that by the end you will have a framework for how the process works, and a good set of pointers and principles for being ready to dive in and submit your first patch -- or your first series. Topics will include: What's a maintainer? How does the development window and feature freeze work? How do I make a good patch series? What if I'm not sure if my code is a good idea or not? What if I need to make a big change and I'm not sure the correct approach?

1. Contributing to Xen
An Introduction

2. We want your patches!

3. Why do we want your patches?
• Individually: Feels good to know our work is useful
• But of course, we’re not paid to feel good — our employers want your
patches too
• Mindshare and “Brand"
• May want to use your code someday

4. “Free software” is free as in…
• “Free” as in “free speech”
• Often “Free” as in “free beer”
• But for a maintainer, open source is often…

5. “Free” as in “free puppy”

6. “Free” as in “free puppy”
• Every extra line of code means:
• More difficult to change or refactor
• More chance a bug needs to be fixed
• Submitter often disappears after the code is
accepted, leaving the maintainer to take
care of it
• Keep that tension in mind as you contribute

7. How does any patch get in?

8. Maintainers
• Nobody has a full understanding of the entire codebase
• The “One Little Change” problem
• Role: Long-term investment in keeping the code “clean”
• xen.git/MAINTAINERS
• xen.git/scripts/get_maintainer.pl
• Nested maintainership
• THE REST

9. Checking in a patch: When
• Approval from all maintainers whose code the patch touches
• Approval or acquiescence from everyone who has raised issues

10. Committers
• “Secretarial” role: Determine proper acks and apply patch
• “Final authority” / “Elder Council” role

11. Conflict resolution
• Try to achieve consensus
• Maintainers can overrule non-maintainers
• “Nested” maintainers can overrule (or stand-in for) lower-level maintainers
• Majority vote of committers can overrule a maintainer

12. Expect Iteration
Very low probability for version 1 of any series to be checked in

13. The Development Cycle

14. Three Phases
• Development window
• Any patch can be checked in
• “Last posting date” (+2 weeks):
• Patches checked in if first version posted already
• Feature freeze (~6 weeks)
• Only bug fixes checked in
• Two releases per year (June and December) WARNING This may change soon

15. Writing a good patch (series)

16. A thousand unwritten rules
(You’re not going to get it right)

17. Consider three audiences
• The Reviewer(s)
• People looking for patches of interest
• The Archaeologist

18. Audience:
The Reviewer
• Is this patch necessary?
• Is this patch the right way to solve the problem?
• Is this patch correct?

19. Audience:
Someone looking for someting
• Patches to backport
• A patch that may have broken something
• Or a patch which fixes something

21. Audience:
The Archaeologist
–“Chesterton’s Fence”
“Don’t ever take a fence down until you
know why it was put up.”

22. Template for a changelog
• What does the current code do?
• Why is that a problem?
• How does this patch fix it?
• Any other changes the patch is making

23. One-line summary
• Give the general area of the code
• “credit2:” “vvmx:”
• Hint of what is changed to know whether it’s worth looking further into

25. Making a series
• A full change may require multiple independent changes
• All changes: A1 B1 A2 C1 C2 B2 D1 A3
• Break down into logical chunks:
• A1 A2 A3
• B1 B2
• C1 C2
• D1

26. Making a series: Bisectibility
• Bisection is a powerful tool to find when something broke
• But it only works if every changset works
• Break down your series into logical chunks, but:
• Don’t break existing functionality
• Don’t introduce bugs in one patch and fix them in another
• Can introduce code that isn’t used
• Don’t introduce code that doesn’t build

27. Coding Style
• Follow the coding style
• xen.git/CODING_STYLE
• xen.git/tools/libxl/CODING_STYLE

28. Mechanics
• git send-email
• --- line
• CC:

30. What [not] to put in a changelog
• References to already-public commits
• Short hash + short title
• 5d3214c (“xen/ept: Rename ept_invalidate_emt*”)
• References to previous discussions
• Summarize in changelog
• Include ref to longer discussion below --- line
• Referencing manuals
• Intel / AMD manuals ‘references’ don’t change
• e.g., Volume 3, 4.4.1

31. Reposting
• Version number (“v2”)
• --version=2
• List the changes

32. All-purpose pass: RFC
• Means “Request For Comments”
• Makes it clear you don’t expect this to be checked in as-is

33. Design Documents

34. Dealing with maintainers
• Communication style
• Unusual but OK: Short and direct
• Not OK: Demeaning
• Judgement call: Being unreasonable
• If you have a problem, contact the community manager
• ‘Pinging’
• If you haven’t heard anything in 2 weeks, reply to your own patch

35. Questions?