Community.o Workshop @ EuroLLVM 2024

Community Community.o
1

This thread is an umbrella for the community.o workshop event at EuroLLVM 2024, similar in spirit to the one from the US dev meeting this fall. Copying @cishida 's guidance from the last event, please include in your post:

  • The areas of improvement your group discussed
  • Tasks and ideas to combat these problem areas
  • How to measure or observe the impact of these tasks

If applicable, please post action items on Issues · llvm/Community.o · GitHub

2

Our table had a discussion on project Leadership, and how to welcome newcomers into the community, but our conversation ended up fixating on how to help newcomers navigate project decision making processes (RFCs).

We came up with these possible actions:

  • Governance: Should we have elected area teams? Check out the governance proposal, LP-0004
    • RFC process is long, it could benefit from timely feedback, with clear output
  • RFC templates: Use templates to document what should be included in the RFC to set it up for success, what is expected, etc.
  • Increase visibility of community meetings:
    • Updates in LLVM weekly, more visibility
  • Document the guidelines for LLVM community social engineering
  • Document existing standard practice for running an RFC, engaging the community, etc

I’m publishing the raw unedit notes here.

3

I was at the round table that discussed “volunteering”, i.e. how to encourage and help people to help with LLVM.

I took a picture of the notes that were taken at the table, not by me. Here is a transcription of the notes with some comments added by me in square brackets and very minor editing to fix one or two spelling mistakes - hopefully without introducing any additional ones :wink: :

  • Slice videos into smaller, digestible ones [this was more about making it easier to learn about LLVM, I guess]

  • Creating small videos during the conferences [i.e. help people make short tutorial videos at the conferences]

  • Making problems more apparent

    • see KDE as an example [KDE was mentioned as an example of a project which provides good helpful information about how to get started contributing to it. I found this “Get involved” website]
    • how much time
    • required level of expertise

  • Sponsorship model

    • become sponsor by providing money
    • become sponsor by providing working hours
    • category for academic work

  • Advertise the benefits of contributing to LLVM

    • highlight on website
    • at community workshops …
1 Like
4

My table was one of the 3 newcomer paths tables.

WHAT DID WE TRY TO FIND OUT?

We attempted to identify newcomer pain points, and attempted to find a way to improve the following flow:

  1. Newcomer begins writing code
  2. They get stuck
  3. They get themselves unstuck somehow (???)
  4. They finish their code, push code to GH

We focused on point (3) in the list.

WHO WAS AT THE TABLE?

Newcomers at the table worked primarily in MLIR and the LLVM backends.

WHAT DID WE LEARN?

… WE NEED TO WRITE MORE DOCUMENTATION :frowning:

Newcomers at the table expressed issues with documentation. In particular, they struggled with:

  • Finding existing documentation/tutorials on high-level concepts
  • Understanding documentation on detailed technical concepts, such as the backends, tablegen, etc.

In particular, a common trend in LLVM projects is that we often rely on what’s effectively oral history from experienced developers down to newcomers. In general, if a newcomer can be paired up with an experienced developer in an appropriate environment, they learn quickly and rarely get stuck.

Newcomers starting out outside of companies and schools that are lucky to have such experienced developers struggle finding out what they need to know.

… OFFICE HOURS CAN BE INTIMIDATING :frowning:

We have attempted to bridge this gap using, for example, office hours. Office hours are events in which an experienced developer volunteers their time to the community, and allows anyone to call in and ask them questions about LLVM.

In general, we agreed that the office hours are useful, but:

  • Discoverability is low
  • Some newcomers may be intimidated and feel as if they are going to “waste someone’s time”

… WE NEED TO UPDATE OUR DOCUMENTATION :frowning:

Certain parts of our documentation, such as the backend, can be out of date or confusing to developers.

… WE NEED TO IMPROVE DISCOVERABILITY OF OUR EXISTING DOCUMENTATION :frowning:

High level concepts, such as “how does LLVM work” are technically already documented, but you have to look for them.

For example, I just tried to find the “high level breakdown of LLVM” and the current best docs we seem to have directly from the docs page are Chris Lattner’s original writings from graduate school.

Technically our docs website has search functionality, but it doesn’t work too well.

We also have beginner tutorials from past conferences but:

  • There are a lot of them
  • It’s not clear which ones are intended for complete newbies versus experienced developers learning about a new piece of LLVM tech
  • The ones that are probably useful are not obviously linked in the documentation

… WE NEED TO MAKE IT EASIER TO UPDATE THE DOCUMENTATION :frowning:

Beginners expressed frustration with updating the documentation.

Particular complaints were:

  • Sphinx is frustrating to work with, they would prefer Markdown. (Note that some of our documentation is already written in Markdown. Example here.)
  • Newcomers would be more inclined to update docs as they run into trouble if it was easy to edit the documentation directly from the page. For example, if we embedded “edit on GitHub” links in the documentation, it would lower the amount of effort to fix/update documentation.

… WE NEED MORE INCENTIVES TO DO “BORING WORK” :frowning:

  • Many experienced developers are often employed to work on LLVM, and their companies often pay them to do specific work, that often does not include documentation. These developers may not work on LLVM outside of working hours.
  • There is little public recognition for doing “boring work” like documentation, office hours, and so on. We should reward people better for doing this sort of work.

… WE NEED TO HELP BEGINNERS ASK THE RIGHT QUESTIONS :frowning:
Some newcomers expressed frustration with asking questions on Discord/Discourse about certain topics and not getting replies.

This often happens when

  1. Nobody knows the answer to the question
  2. The question lacks necessary context for someone to answer it accurately

WHAT DO WE DO WELL RIGHT NOW?

WHAT CAN WE DO TO IMPROVE THE SITUATION?

… WHAT DOES OUR IDEAL “GETTING UNSTUCK” FLOW LOOK LIKE?
From the above complaints, we can say that if we can make the following flow more likely, we’ll reduce newcomer frustrations with the project:

  1. Newcomer writes some code
  2. Something is broken.
  3. Newcomer consults the documentation. If they find the answer to their question, they are done.
  4. If not, the newcomer goes to Discord or Discourse, and asks a question. A more experienced developer helps them.
  5. The newcomer fixes their code
  6. The newcomer improves the existing documentation, so that future developers do not run into the same issue

… HOW CAN WE GET THERE?

  • We could restructure LLVM’s documentation in the form of a Rust-style book. Notice in particular that each page in the book has a link to the associated GitHub repo, making it clear to know where/how to edit the docs.
  • We can write some documentation or a template on how to write a good question.
  • We can identify pieces of documentation that are out of date and known to be incorrect, and update them
  • We can identify the most common repeated questions from developers on Discord and Discourse, and see if we can prevent the repeated questions through documentation

… HOW DO WE BETTER RECOGNIZE “BORING WORK”?

  • We could have a “developer of the month” sort of thing which recognises members of the community who are doing a lot of community work
  • We could encourage employers to reward employees for doing “boring work”-- it improves their engineers’ standing in the community, and makes it easier for more people to contribute to LLVM. In theory, they rely on LLVM in some way, so encouraging their people to help others write quality code + maintain that project ought to be good for them too.
6 Likes
5

I was a part of the discussion on collaborating/interfacing with other communities.

Here is an outline of some of the things what we discussed:

  • Java/dynamic language communities vs C/C++/Rust
    • From an academic lens, there is a lack of communication between the groups. Research often seems to be duplicated.
      • Why are different communities not using certain techniques from the other?
      • Why are both communities reinventing techniques that the other has already implemented.
      • Some things might not be directly translatable, but there is a lot of overlap.
    • People also pointed out similar issues between the LLVM community and the GCC community.
  • Discussion on whether or not licensing is a barrier between LLVM and GCC:
    • Mentions of there being some issues. GCC’s licensing is somewhat more restrictive.
    • This is not really clear for developers who are not legal experts.
    • These barriers, whether actual or artificial can limit interactions.
    • Ideas are almost never restricted however.
      • Ideas from papers/publications can usually easily be moved around.
      • Moving raw code around is much less clear and can be significantly more complicated.
  • Discussion about interaction with less compler-y communities:
    • Some friction with driver groups that are downstream consumers of LLVM.
      • (Note that this bullet point consists of my thoughts that I didn’t mention during the round table): This seems mostly like a lack of communication. It might take 45 seconds for a LLVM developer to look at someone else’s pass pipeline and point out possible issues/improvements with their expertise. Having better communication between these communities (consult a compiler/LLVM-expert for 5 minutes?) I think would help. This does require a time investment though.
    • Linux plumbers conference - can be complicated due to not always talking
    • Developer tooling?
    • Part of the problem seems to be an over focus on your specific problem space. The incentive to reach out and communicate seems to be missing.
      • Better bug reports might help a little bit, but would require a decent amount of effort.
    • MLIR is fed by other projects
      • Ensures collaboration
      • A formal forum to guide collaboration
      • Still some tension, like needing some stability for proper interaction
        • Some discussion about versioning
      • Also connected to ML communities
      • No real forum with stakeholders active in both communities.
      • ML for compilers can be in a similar space.
  • Looking at solutions from other OSS groups:
    • C and C++ standards committees:
      • Established an official role to act as a liaison between the two committee groups.
      • Can help move/connect things between groups.
    • Carbon project
      • Explicitly interviewing organizers of other communities.
      • Found success being more intentional about collaboration/where problems are in the collaboration pipeline, with an explicit action point of interviewing leaders in related communities.
      • Dealing with feedback from interviews was easier than expected, with most of it being easily actionable.
  • LLVM can be seen as somewhat well organized relative to other communities.
  • Fanpeonism can be an issue.
    • Presenting collaborations publicly can help prevent this.
      • Keeping things closed can be an issue. Anecdote of this being an issue in the C/C++ working group liaison groups being more closed.

Here are the raw handwritten notes in case I’ve missed something in the transcription above:

6

I took notes at the “community growth” table.
We mostly talked about pain points for new contributors.

We ended up mostly raising points very similar to what the other tables on the topic came up with, see the notes published up-thread by @barrelshifter.

I’ll try to not to repeat most of the points there, just highlight a few our table raised.

Most of what we talked about seemed to be variations of “how can we help newcomers overcome social anxiety to start interacting with experienced people?”. A key feedback is that it is less daunting to start text chatting on Discord (albeit still daunting) than just calling in to an office hours where you didn’t talk with the host before.