Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

XPDDS19 Keynote: Patch Review for Non-maintainers - George Dunlap, Citrix Systems UK Ltd

31 views

Published on

As the number of contributions grow, reviewer bandwidth becomes a bottleneck; and maintainers are always asking for more help. However, ultimately maintainers must at least Ack every patch that goes in; so if you're not a maintainer, how can you contribute? Why should anyone care about your opinion?

This talk will try to lay out some advice and guidelines for non-maintainers, for how they can do code review in a way which will effectively reduce the load on maintainers when they do come to review a patch.

Published in: Software
  • Be the first to comment

  • Be the first to like this

XPDDS19 Keynote: Patch Review for Non-maintainers - George Dunlap, Citrix Systems UK Ltd

  1. 1. Reviewing for Non-Maintainers George Dunlap
  2. 2. Maintainers would love to have more help reviewing
  3. 3. …but many people don't know where to start
  4. 4. Absolutely perfect Ready to be checked in Not so perfect
  5. 5. Goal Help move a patch closer to being ready to be checked in
  6. 6. But: “First, do no harm”
  7. 7. Not so helpful: Giving feedback the maintainer has to contradict
  8. 8. Not so helpful: Beat up the new guy
  9. 9. Not so helpful: Looking for things to criticize
  10. 10. Helpful: Helping get the patch checked in
  11. 11. Necessary? Architecture Interface Effective Efficient All Cases Correct Robust / Maintainable Coding Style Patch / Series
  12. 12. Necessary? Architecture Interface Effective Efficient All Cases Correct Robust / Maintainable Coding Style Patch / Series
  13. 13. Necessary to accomplish goals? • Is it clear what the goals are? • Do we need to make a change, or can the goals be met with existing functionality?
  14. 14. Necessary? Architecture Interface Effective Efficient All Cases Correct Robust / Maintainable Coding Style Patch / Series
  15. 15. Architecture / Interface • Is this the best way to solve the problem? • Is this the right part of the code to modify? • Is this the right level of abstraction? • Is the interface general enough? Too general? Forward compatible?
  16. 16. Necessary? Architecture Interface Effective Efficient All Cases Correct Robust / Maintainable Coding Style Patch / Series
  17. 17. Functionality • Does it do what it’s trying to do? • Is it doing it in the most efficient way? • Does it handle all the corner / error cases correctly?
  18. 18. Necessary? Architecture Interface Effective Efficient All Cases Correct Robust / Maintainable Coding Style Patch / Series
  19. 19. Maintainability / robustness • Is the code clear? Appropriately commented? • Does it duplicate another piece of code? • Does the code make hidden assumptions? • Does it introduce sections which need to be kept “in sync” with other sections? • Are there other “traps” someone modifying this code might fall into?
  20. 20. Style • Comments,carriage returns, “snuggly braces”, &c • See CODING_STYLE and tools/libxl/CODING_STYLE • No extraneous whitespace changes
  21. 21. Patch • Informative one-line changelog • Full changelog • Motivation described • All important technical changes mentioned • Changes since previous revision listed • Reviewed-by’s and Acked-by’s dropped if appropriate
  22. 22. Consider three audiences • The Reviewer(s) • People looking for patches of interest • The Archaeologist
  23. 23. Audience: The Reviewer • Is this patch necessary? • Is this patch the right way to solve the problem? • Is this patch correct?
  24. 24. Audience: Someone looking for someting • Patches to backport • A patch that may have broken something • Or a patch which fixes something
  25. 25. Audience: The Archaeologist –“Chesterton’s Fence” “Don’t ever take a fence down until you know why it was put up.”
  26. 26. 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
  27. 27. Reviewing tips • Code follows data: Look at the data structures first • Three ways to look at a patch • Look at the patch itself (emacs / vim ‘diff mode’) • Look at the patched file • Graphical diff (i.e., meld)
  28. 28. Communication: Express Appreciation • “Thanks for the patch.” • “Thanks for doing this.” • “Looks good, just a few comments.” • “I think this is a good change.”
  29. 29. Communication: Avoid inflammatory language; stick to the facts
  30. 30. Strongly-worded dictionary entry: "裹脚 (guo3 jiao3): foot-binding (a vile feudal practice which crippled women both physically and spiritually)”
  31. 31. Wikipedia Entry on Foot-Binding: "Foot-binding resulted in lifelong disabilities for most of its subjects. … Binding usually started during the winter months since the feet were more likely to be numb, and therefore the pain would not be as extreme. …The toes on each foot were curled under, then pressed with great force downwards and squeezed into the sole of the foot until the toes broke…”
  32. 32. Why you shouldn’t say code is “garbage” • Makes the patch author angry • They spend time and mental energy wrestling with their feelings rather than coming up with solutions • Doesn’t contain any information • The facts are both more powerful and more persuasive
  33. 33. Your experience is a fact • Example: • “This confusing” • “It took me a long time to figure out what was going on here” • Example: • “This is fragile” • “This seems fragile to me” • “If X happens, Y will happen.”
  34. 34. Necessary? Architecture Interface Effective Efficient All Cases Correct Robust / Maintainable Coding Style Patch / Series

×