jj Community Governance Survey Report

[nasamuffin]

The governance working group (Austin Seipp/aseipp/@thoughtpolice, Waleed Khan/@arxanas , Martin von Zweigbergk/@martinvonz, and Emily Shaffer/@nasamuffin) ran a survey of jj community members from August 14 through the present. We advertised this survey in Discord and on GitHub.

We're pleased to share a summary of the results of the survey. If you're interested in getting the anonymized response set to do your own analyses, just reach out to any working group member, and we'll be happy to share that data.

Demographic of Responses

From August 14 to October 1, 2024, we had a total of 30 responses.

We asked respondents to self-report the type of contributions they make. This question allowed selecting multiple responses, so it's not surprising that nearly everyone uses jj.

Very few respondents are working on documentation, first- or third-party. Later in the survey we saw respondents requesting work on jj's documentation, so the gap is clear: we seem to have few people working on documentation, so the quality of documentation is suffering.

We also found that around ⅓ of respondents are contributing only in the form of user feedback and/or bug reports, and close to ½ of respondents are not writing code at all.

Prioritization of Projects for the Working Group

We asked respondents to choose their top 3 priorities for the working group to contribute to. Keep in mind that the goal of the governance working group is to establish the structures and processes for the project, rather than to directly address these priorities.

We calculated these based on a weighted system; 1st priority was worth 3 points, 2nd priority was worth 2 points, and 3rd priority was worth 1 point. With this weight, we found the following priority list:

• Improving jj's documentation (tutorials, user guides, etc.): 54 points
• Establishing a process for technical decisionmaking (including RFC): 31 points
• Establishing a technical design/"RFC" process: 23 points
• Establishing official code review policy (such as a "two-reviewer" policy): 17 points
• Improving jj's user support experience: 15 points
• Encouraging corporate participation and establishing guidelines: 15 points
• Exploring a jj user/contributor summit: 12 points
• Improving jj's social media presence: 9 points

Plus priorities from the "other" field:

• Defining a roadmap/target feature set: 3 points
• Clarifying platform support policy/intention: 1 point
• New contributor onboarding: 1 point

(Note: Some respondents also included technical feature requests in this field. These are valuable feedback, but have not been included in the response summary since they are outside the scope of this working group.)

What Comes Next?

Prerequisites

A few weeks ago, we established an interim voting process to allow the community to approve governance structures. With this process, we can start getting changes into place to address some of the projects the community asked us to prioritize.

The way we are thinking about these solutions so far, many processes are predicated on the creation of an authoritative body; we have ideas for what this looks like and are very close to starting stage 1 of the interim process to start getting community approval for this general authoritative structure. We're also likely to tackle establishing guidelines for corporate participation in the process of setting up this structure, to avoid the project being overly influenced by any one entity (and, in the process, hopefully encourage other corporate entities to participate, knowing that they have avenues to protect their investment and influence the project roadmap).

Documentation Concerns

We recognize that many community members are unhappy with the documentation. The governance working group is intended to form governance structures, not lead implementation efforts, so with the current state, we aren't able to do much beyond sympathize. We're open to suggestions about ways to improve the documentation, like naming a maintainer or committee to identify and execute a documentation improvement roadmap, or hosting a doc-fix-a-thon, or advice for attracting and retaining writers to help us out with the docs. Please feel free to weigh in with your recommendations in the Discord chat.

Technical Decision-making Process

Following the establishment of some authoritative body, like a steering group, this is next on the roadmap for the working group. It's likely to include the design doc/RFC process, but may also need to decide on less formal discussions which didn't follow an RFC process directly or which aren't a good fit for that process;. The steering group will have the ultimate say in approving technical decisions and resolving technical conflicts.

Code Review Policy

This comes next after we land a technical decision-making process. We're currently thinking to establish clear criteria for how to become a reviewer, how to become an approver, and how to remove someone from those roles. We expect to also do some work with the GitHub configs to enforce these processes. We still want to stick to the spirit of the conflict-of-interest section of the current code review guidelines.

Defining a Roadmap

After seeing so many write-in responses asking for a roadmap, Martin put together an informal one. Thanks for your responses! This is likely to become tied to the technical decision-making process as well.

Other Projects

We're still hoping for the governance working group to have a short lifetime (our goal is to dissolve the working group this year; that feels a little ambitious, but we want to try). It's not likely that we will address 100% of the projects that received upvotes during the survey. However, we do expect that the authoritative governance body we establish will continue to address these projects - for example, the steering group can choose to establish sub-groups to organize our user support policy, or set up a summit, or wrangle documentation.