[all][dev][ops][tc] Bridging the gap between community and contributing orgs
The tl;dr on this is that I'm opening a broad community discussion on how we can, collectively through improved communication, better bring together our established contributors with casual and prospective contributors who struggle to find successful patterns of contribution, so that we might all support each other in order to benefit OpenStack as a whole. Read on for details...
OpenStack's TC has requested that foundation staff, when in conversation with representatives of member organizations, encourage participation in the project and collect feedback on any related challenges those organizations encounter in their attempts to do so. In order to better understand the feedback and brainstorm achievable recommendations for the broader community[*], Community Managers on the foundation staff started to work with a small focus group of established contributors with a solid understanding of what successful patterns of contribution look like. It also came to light that established contributors experience many of the same sorts of challenges, even more so if they don't have the luxury of focusing full-time upstream, and so success often comes down to knowing how to effectively navigate those challenges. The community's goal with this exercise is to improve everyone's experience, and your help is needed to do that!
The most common themes reported by those struggling to contribute are not related to tooling or workflow confusion, but instead seem to come down to basic communication challenges. Ideas so far to address these gaps include:
* Review bandwidth - Ensure contributors and companies understand the importance and benefits of code review - Incentivize and credit meaningful "+1" reviews more - Understand that the volume of changes and limited reviewer bandwidth often means proposals aren't reviewed quickly (or at all), and their proponents may need some additional tenacity and engagement with the team to get their work noticed - Utilize "review dashboards" as a way to find stale changes which have fallen through the cracks * Review strategy and etiquette - Be clear about the meaning of votes on changes, especially negative ones, and set explicit timelines for things like "procedural -2" or WIP blocks when their approval needs to be delayed - Focus on comments and requests that affect whether or not the change can be merged after the fixes are submitted, rather than requesting trivial adjustments to an unsuitable change which has more fundamental problems - Reciprocate with reviews of changes from new reviewers you see leaving insubstantial reviews, demonstrating to them what deeper and more meaningful reviewing looks like * Mentoring newcomers - Established contributors with sufficient bandwidth can help mentoring newcomers, potential core reviewers and new leaders - Mentoring can happen as part of internship programs as well as by helping newcomers determined to become active contributors; both ways should be embraced and utilized
What challenges are you facing? And, how would you improve them?
Two weeks from now, we'll have a forum session at the OpenInfra Summit Asia in Suwon[**] where our community can refine these possible approaches and integrate others, as well as bring attention to them and promote their application. I've also proposed a similar forum session for OpenInfra Days North America in Indianapolis a month after that, where we can hopefully continue this conversation.
The goal for this multi-stage effort is to improve the contribution experience for established participants, casual contributors and newcomers alike. While it's easy to jump to blaming in these situations, it will be far more productive if we can focus on the challenges and experiences that we would each like to remove or improve for ourselves and others in our community. As we find ways together to improve our efficiency, we can reduce the load on all contributors and lower the barriers for people to join and participate.
[*] https://etherpad.opendev.org/p/r.2205024e55689bccb82c20c960853cb5 [**] https://2024.openinfraasia.org/a/schedule#view=calendar&title=Bridging%2...
On 2024-08-21 15:18:12 +0000 (+0000), Jeremy Stanley wrote: [...]
The most common themes reported by those struggling to contribute are not related to tooling or workflow confusion, but instead seem to come down to basic communication challenges.
[...]
Last week, Jens mentioned this article in IRC:
https://www.chiark.greenend.org.uk/~sgtatham/quasiblog/code-review-antipatte...
Coincidentally published the same day I posted the first message in this thread, it's an amusing semi-satirical look at many of the same challenges our community has also identified. A quick summary of the author's points (though I strongly encourage you to check out the full article if you have time):
* Batch up review feedback and try not to "move goalposts" by repeatedly coming up with new problems in subsequent reviews that you could have found the first time through (i.e. don't just stop reviewing on the first issue you find).
* Don't demand a change author include unrelated fixes to nearby code (pointing it out as optional in case they want to tackle it if they have time is fine, just be clear it's not a requirement of approval).
* Try to reach a consensus of opinion with other reviewers on the same changes/project, and avoid jerking the author around by changing your own opinion on things.
* If a proposed implementation is unsuitable, be clear about what kind of alternative implementation would be suitable.
* Lead with the most important problems in a change, not the trivial ones.
* When reviewing individual changes that are part of a larger approved specification, try to focus on whether those changes implement the spec as written regardless of whether you agree with choices the project has made within the spec (if you disagree, get the spec changed or amended first).
* Extremes of opinion can always be found to reject a change, so look for a position of compromise when possible.
* Be cautious and deliberate about shifts of expectation over time, since authors are prone to replicate patterns from prior changes and existing code.
I think articles like this help to confirm we're on the right track, and I find it a reassuring reminder that these are challenges pretty much all communities struggle with. We're not alone. If we can come up with viable approaches for improving the situation, we'll be helping not just our own community, but open source software projects everywhere.
Also, a quick reminder: If you'll be in Suwon for OpenInfra Summit Asia or Indianapolis for OpenInfra Days North America, come to the forum session (Bridging the Gap: Community and Contributing Orgs). Whether or not you're available for the in-person sessions, replies to this mailing list thread can help refine the community's approach to contributor communications so we can start to get some of these things documented in relevant places (Contributor Guide, Project Team Guide, et cetera).
Hi Everyone,
Jeremy mentioned the Forum session on this topic, which was scheduled for Tuesday (September 3) week at the OpenInfra Summit Asia. I moderated the session on behalf of Jeremy, and reaching out here to share a recap.
We had a great conversation with people who were able to join the discussion at the Forum session. Below is a brief summary of what the group talked about, which included sharing experiences and brainstorming about ideas to reduce current challenges that people are facing, both newcomers as well as casual and established contributors. Our conversation touched on three main areas, which were challenges, solution ideas and next steps.
Challenges - We have less active developers and maintainers * Vendor companies have been the main group of organizations who invested in OpenStack development upstream, but those investments have reduced by today * Operators, who are around, have less capacity to work upstream, and their focus is more on bug fixing than adding new features - False assumptions * Maintainers have full-time allocation to work on OpenStack * Code review is the only way, outside of code contributions, for companies to provide meaningful help to the community - Project team priorities need to be more clear, and project management type of work is required to use the teams’ bandwidth more efficiently * Sometimes the process is in place, but not visible for people who are not engaged on IRC, etc - Even in case of established contributors, they often need to ping people on an ongoing basis to get their reviews to move forward, this method does not scale
Solution ideas - Education on open source investment and forms of involvement needs to continue * Companies still spend big chunks of money on proprietary SW development, they need to understand the reasons and benefits to also invest in working on open source projects they rely on, such as OpenStack - Documented and visible processes * OpenStack project teams need to revisit their processes to make sure that the contributors are spending their time and efforts efficiently * When processes exist they also need to be discoverable by everyone, without the need to talk to an established contributor or maintainer - Code review is not the only area where maintainers need help. When an individual or comany, like an operator, has expertise in particular features or areas of the code, their input is needed and desired when changes are made to those parts of the code. - Tooling is not the solution to many of the challenges, so we need to focus on solving the social issues
Next steps - Documentation and making existing processes visible, folks from the Nova team made a commitment to update their existing documentatoion to make it up to date and contain their current processes on how they do project management for the team * The Nova team also started to track bug fixes as part of their process to track changes and have the ability to prioritize, in recognition how that is an area where operators often get involved - Start small and replicate practices that works in the wider community * When project teams find ways that help their work, the community should consider exploring and adopting those techniques more widely
For more detailed notes, please check the etherpad we used for the session: https://etherpad.opendev.org/p/r.914969755fedc5c6fa58d7e9881ffa66
Those who attended the Forum session, please chime in with any further thoughts and notes on anything that I missed to mention, and to continue the conversation.
Those of you who did not have the opportunity to participate in the Forum session, what from the above summary and notes on the etherpad do you resonate with? Which experiences do you have as well and what solution ideas have you tried already?
Best Regards, Ildikó
———
Ildikó Váncsa Director of Community Open Infrastructure Foundation
On Aug 29, 2024, at 4:18 AM, Jeremy Stanley fungi@yuggoth.org wrote:
On 2024-08-21 15:18:12 +0000 (+0000), Jeremy Stanley wrote: [...]
The most common themes reported by those struggling to contribute are not related to tooling or workflow confusion, but instead seem to come down to basic communication challenges.
[...]
Last week, Jens mentioned this article in IRC:
https://www.chiark.greenend.org.uk/~sgtatham/quasiblog/code-review-antipatte...
Coincidentally published the same day I posted the first message in this thread, it's an amusing semi-satirical look at many of the same challenges our community has also identified. A quick summary of the author's points (though I strongly encourage you to check out the full article if you have time):
- Batch up review feedback and try not to "move goalposts" by
repeatedly coming up with new problems in subsequent reviews that you could have found the first time through (i.e. don't just stop reviewing on the first issue you find).
- Don't demand a change author include unrelated fixes to nearby
code (pointing it out as optional in case they want to tackle it if they have time is fine, just be clear it's not a requirement of approval).
- Try to reach a consensus of opinion with other reviewers on the
same changes/project, and avoid jerking the author around by changing your own opinion on things.
- If a proposed implementation is unsuitable, be clear about what
kind of alternative implementation would be suitable.
- Lead with the most important problems in a change, not the trivial
ones.
- When reviewing individual changes that are part of a larger
approved specification, try to focus on whether those changes implement the spec as written regardless of whether you agree with choices the project has made within the spec (if you disagree, get the spec changed or amended first).
- Extremes of opinion can always be found to reject a change, so
look for a position of compromise when possible.
- Be cautious and deliberate about shifts of expectation over time,
since authors are prone to replicate patterns from prior changes and existing code.
I think articles like this help to confirm we're on the right track, and I find it a reassuring reminder that these are challenges pretty much all communities struggle with. We're not alone. If we can come up with viable approaches for improving the situation, we'll be helping not just our own community, but open source software projects everywhere.
Also, a quick reminder: If you'll be in Suwon for OpenInfra Summit Asia or Indianapolis for OpenInfra Days North America, come to the forum session (Bridging the Gap: Community and Contributing Orgs). Whether or not you're available for the in-person sessions, replies to this mailing list thread can help refine the community's approach to contributor communications so we can start to get some of these things documented in relevant places (Contributor Guide, Project Team Guide, et cetera). -- Jeremy Stanley
participants (2)
-
Ildiko Vancsa
-
Jeremy Stanley