[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%20the%20Gap -- Jeremy Stanley
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
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
A quick reminder: If you'll be in Indianapolis for OpenInfra Days North America next week, come to the "Bridging the gap between community and contributing organizations" Forum session at 11:20 AM EDT on Tuesday in room 305. If you can't make it, don't worry! Later this month, a cross-project PTG session is booked for 17:00 UTC on Tuesday (October 22) under a "bridging-the-gap" track name. Whether or not you're available for the above synchronous discussions, 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
On 2024-10-10 00:37:30 +0000 (+0000), Jeremy Stanley wrote:
A quick reminder: If you'll be in Indianapolis for OpenInfra Days North America next week, come to the "Bridging the gap between community and contributing organizations" Forum session at 11:20 AM EDT on Tuesday in room 305.
The OID-NA session was a great success, with at least a dozen participants (I should have counted, sorry!). You can find the notes at https://etherpad.opendev.org/p/r.06f725e22f12d0e72639b5ac0c8bdac3 but with only 40 minutes we didn't get too deep into details. We talked a bit about how the list of findings and recommendations, and how they're categorized so far, resonated with people in the room. Some related personal experiences where they felt their proposed changes were not evaluated fairly or concerns taken seriously. There seemed to be consensus that perceived affiliation influences were likely to be merely statistical reality or at worst subconscious bias, and that communication challenges like those we've already highlighted are primarily emergent social behaviors, habits or basic human tendencies which are best addressed through education and documentation rather than technical means. There was a bit of debate about letting the perfect be the enemy of the good when it comes to the absence of suitable test environments for specialized hardware integration, and we talked some about the possibility or challenges of third-party testing vs including some research clouds into OpenDev's stable of available resources. Participants also saw value in having more clearly documented escalation paths for technical disagreements (core reviewer... team consensus... PTL... TC). These topics spilled over into an "OpenInfra leaders" session later, so https://etherpad.opendev.org/p/r.90cac8145c6e01bc19d7c02d4df6f8b3 is worth reviewing as well (around lines 16-23).
If you can't make it, don't worry! Later this month, a cross-project PTG session is booked for 17:00 UTC on Tuesday (October 22) under a "bridging-the-gap" track name. [...]
That's right, past me! I'm hoping we can use the session tomorrow to start divvying up writing tasks and identifying which documents might be the most appropriate locations for the amassed recommendations. Everyone's welcome, but people willing to volunteer to work on some of this are even more welcome. ;) In addition to tomorrow's PTG session on this topic, the TC devoted an hour to their role in the effort earlier today, notes begin around line 317 in https://etherpad.opendev.org/p/r.0f25532f564fb786a89cfe1de39b004b for those of you interested in an early recap. -- Jeremy Stanley
On 2024-10-21 23:57:09 +0000 (+0000), Jeremy Stanley wrote: [...]
I'm hoping we can use the session tomorrow to start divvying up writing tasks and identifying which documents might be the most appropriate locations for the amassed recommendations. Everyone's welcome, but people willing to volunteer to work on some of this are even more welcome. ;)
In addition to tomorrow's PTG session on this topic, the TC devoted an hour to their role in the effort earlier today [...]
Now that people are hopefully recovered and recharged from the PTG, and settling in for quieter times as the end of the year approaches, it's a good opportunity to take stock of where we are on this effort. First, for those who missed the TC session and haven't had a chance to peruse the notes yet, https://etherpad.opendev.org/p/r.0f25532f564fb786a89cfe1de39b004b#L321 is a fairly quick read. For an even quicker summary, we had a brief (re)introduction to the overarching topic and recap of past discussion series, as well as perceived next steps. Some specific ideas were also floated like better documentation on using Matrix to access OFTC IRC, expanding on the "escalation path" suggestion from OID-NA, scheduling project review days and sharing dashboards to reduce the number of changes going unnoticed, better gate stability as a means to improve contributor experience, revisiting how strict projects need to be about testing for hardware-specific features, and making reviewers/maintainers more visible so new contributors can find and talk to them. The dedicated working session used https://etherpad.opendev.org/p/bridging-the-gap-series-4 as a breakdown of previously discussed suggestions. Each item is templated out for additional notes as guidance for volunteers to elaborate on their intended meaning, and a best guess for which parts of what existing documents seem like the most appropriate locations to add or expand on these. We talked about the obvious documents (central contributor guide, per-project contributing docs, project team guide...), but also some non-traditional ideas like resurrecting the Gerrit "WelcomeBot" or canned welcome messages and direct outreach for reviewers. We only got through a couple of items in the series 4 pad, more or less to prove out the workflow, so this is where the rest of you come in! Please take a look at the pad and, if you see a suggestion which is of particular interest to you, please help expand on it, suggest a location (or multiple locations) where it can be documented for improved visibility, and volunteer to push changes! Also feel free to follow up here with any questions or ideas you have for helping move the effort forward to bridge these gaps. -- Jeremy Stanley
participants (2)
-
Ildiko Vancsa
-
Jeremy Stanley