How to tame a maintainer

Contributing to Open Source is hard. Too often we submit a pull request without hearing back from the maintainers, wasting our time that could be spent elsewhere. Being a long time open source contributor, and just recently maintaining MetalLB, a fairly popular open source project, I will share the insights and the issues a contributor (and a maintainer) faces when dealing with new contributions.

I will provide hints and reasons to maximize the chances to steer the maintainers' attention to our work, to gain their trust and establish a profitful relation with the community behind a project.

Talk presented at Opensource day 2023 (osday.dev)

Transcript

1. How to tame a maintainer Federico Paolinelli - Red Hat
2. Telco Network Team @ Red Hat Contributed to: - Athens - KubeVirt - SR-IOV Network Operator - OPA Gatekeeper - OVN-Kubernetes hachyderm.io/@fedepaol - CNI Plugins @fedepaol - MetalLB fedepaol@gmail.com About me
3. Why this talk?
4. Back in 2013…
7. Then, to 2018..
10. Today
11. MetalLB MetalLB is a load-balancer implementation for bare metal Kubernetes clusters, using standard routing protocols (github.com/metallb/metallb) - 5k stars on github - ~ 600 PRs since I started maintaining the project - ~ 40k LOC
12. How to tame a maintainer https://flic.kr/p/4F1DB9
13. No Silver Bullet!
14. The Context
15. The Project
16. Your feature Insert a nice feature here
17. Dramatis Personae
18. The Contributor (you) Priorities: • Get the feature he needs in the project
19. The Maintainers Priorities: • Find the root cause of the escalation that is going on for weeks • Deliver the feature promised to the customer • Try to understand why the CI is flaking and they are not able to reproduce it locally • Find the time to review all the PRs that keep accumulating • …. • Do the laundry • Your feature they never heard about
20. The maintainers’ first reaction will be to Push Back
21. Submitting the PR straight away is generally a bad idea
22. You need to build Reputation
23. Contributors are a rare commodity
24. Contributing to Open Source is about giving something for something else
25. Where to start from
26. Contributions must be Meaningful
27. from https://github.com/metallb/metallb/issues Good first issues
28. Triage existing issues reported by users https://flic.kr/p/aA3sHP
29. Extend the CI / Automation https://flic.kr/p/9b24xc
30. First steps • (Say hi) • Declare your intention • Ask if you can work on it • Start working until submitting a PR...
31. And this is just the beginning https://flic.kr/p/5Gm38m
32. Open Source is different from what you are used to
33. Once submitting the PR, you’ll get reviews • Reviews are really thorough • As a new contributor, maintainers will keep a higher bar • You’ll need to defend your ideas • You’ll have to accept critics and suggestions (or both)
34. Open Source is about communicating https://flic.kr/p/9SCd2b
35. Meet them!
36. But I only care about my feature!
37. The Maintainers Priorities • Find the root cause of the escalation that is going on for weeks • Deliver the feature promised to the customer • Try to understand why the CI is flaking and they are not able to reproduce it locally • Find the time to review all the PRs that keep accumulating • …. • Do the laundry • Put the kids to bed • Your feature they never heard about
38. Reputation Unlocked!
39. On submitting the feature
40. Submitting the PR straight away is generally a bad idea
41. On proposing a new feature • Discuss it during community meetings • Prepare a draft proposal • Show that you care about impacts (possible alternatives, API changes, how to extend the coverage of tests) • You must convince the maintainers that the project will benefit from it
42. Submit the PR….
43. Submit the PR….
44. Be Kind
45. Sometimes it’s hard https://flic.kr/p/J88ZHx
46. Conflicts • With reputation, you’ll work on more complex tasks • With more complex tasks, there will be different opinions • There will be conflicts
47. You’ll initially be a second class citizen • Your PRs might still be ignored • The maintainers may decide the feature you spent so much time on is not wanted anymore • They may give unrelated comment / ask to redesign the whole thing
48. “Of course, I'd also suggest that whoever was the genius who thought it was a good idea to read things ONE F*CKING BYTE AT A TIME with system calls for each byte should be retroactively aborted. Who the f*ck does idiotic things like that? How did they not die as babies, considering that they were likely too stupid to find a tit to suck on?” from https://lkml.org/lkml/2012/7/6/495 People may be rude
49. Traits of a good PR
50. Quality flic.kr/p/sFZ9CW
51. - Multiple people may need to contribute to the project - Readability / maintainability is emphasized - The purpose must be clear - The architecture must be maintainable Why quality matters
52. - Idiomatic code - Naming variables, functions and objects accordingly - Testable - Clean Why quality matters
53. Commit messages flic.kr/p/2cJe67A
54. - Fixed #12345 - Fallback to single stack - MYPROJ-41256 - Improvements - No description provided (Not so) good commit subject / body
55. Good commit subject / body e2e: remove JSON progress output on stdout The original intention was to address "frustration of end users running the e2e suite is that they take a significant amount of time and it is difficult to gauge progress". But Ginkgo's output is different now than it was in Kubernetes 1.19. If users want to see progress, then "ginkgo --progress" might provide enough information. Printing to os.Stdout doesn't work as intended anyway when output redirection is enabled (the default for parallel runs) and causes these JSON snippets to appear as "show stdout" for each failed test in a Prow job, which is distracting.
56. Good commit subject / body e2e: remove JSON progress output on stdout The original intention was to address "frustration of end users running the e2e suite is that they take a significant amount of time and it is difficult to gauge progress". But Ginkgo's output is different now than it was in Kubernetes 1.19. If users want to see progress, then "ginkgo --progress" might provide enough information. Printing to os.Stdout doesn't work as intended anyway when output redirection is enabled (the default for parallel runs) and causes these JSON snippets to appear as "show stdout" for each failed test in a Prow job, which is distracting. The area
57. Good commit subject / body e2e: remove JSON progress output on stdout The original intention was to address "frustration of end users running the e2e suite is that they take a significant amount of time and it is difficult to gauge progress". But Ginkgo's output is different now than it was in Kubernetes 1.19. If users want to see progress, then "ginkgo --progress" might provide enough information. Printing to os.Stdout doesn't work as intended anyway when output redirection is enabled (the default for parallel runs) and causes these JSON snippets to appear as "show stdout" for each failed test in a Prow job, which is distracting. The what
58. Good commit subject / body e2e: remove JSON progress output on stdout The original intention was to address "frustration of end users running the e2e suite is that they take a significant amount of time and it is difficult to gauge progress". But Ginkgo's output is different now than it was in Kubernetes 1.19. If users want to see progress, then "ginkgo --progress" might provide enough information. Printing to os.Stdout doesn't work as intended anyway when output redirection is enabled (the default for parallel runs) and causes these JSON snippets to appear as "show stdout" for each failed test in a Prow job, which is distracting. The why
59. Good commit subject / body https://cbea.ms/git-commit/
60. - Smaller commits are easier to review - It’s easier to scope and write a commit message if it relates to a smaller change - It’s easier to do backports Different commits for different sections
61. “Will clean / add tests / add docs in another PR” Tests
62. Documentation flic.kr/p/ooqPHW
63. Wrapping up
64. - The maintainers care about the project, not the thing you are proposing - You need to earn their trust - You must convince the maintainers that the project will benefit from what you propose - The quality of what you submit must be high Wrapping up
65. You can’t always win https://flic.kr/p/dy59SD
66. but when you do… https://flic.kr/p/ckeawE
67. Did I learn the lesson?
69. Thanks! Any questions? @fedepaol fedepaol@gmail.com Slides at: speakerdeck.com/fedepaol fpaoline@redhat.com