Rules of engagement in an open source issue board

An open source project’s issue board is where many interesting discussions and ideas can emerge. If handled improperly, it can be a hostile and inaccessible space. To ensure that a project’s issue board is a space for productive and mutual discussion, it helps to put in place some guidelines in place to ensure that the discussion is productive.

Crack down on trashing other projects

It’s likely that if someone is interacting with the project in your issue board, they are probably pretty passionate about what the project is doing. Although passion can produce a positive energy towards the project, it can also create a negative energy towards “competing” projects.

Focus on the problem, not the tools

When resolving a problem, criticizing the tools is (most times) a red herring for the real problem. In this case, tools are things like linters, packagers, bundlers, and so on that help aid in the development process. Unless absolutely necessary, steer the conversation away from talking about tools to the problem at hand.

Limit drive-by opinions

Some issues reach a certain degree of virality and can gain traffic from folks that might not totally be invested in the project. This leads to a lot of drive-by opinions. Drive-by opinions are usually not related to the specific topic being discussed and are written to reinforce an opinion rather than an idea. Things like “Don’t use tool X because it’s slow” or “Don’t do this or I won’t use this tool” are examples of drive-by opinions.

Links are your best friend

It’s easy to assume that the people that you are engaging with have the same knowledge that you do. There’s nothing inherently bad about it. Assumptions make it easier to write down complex ideas but it’s important to go back and add the appropriate context before submitting anything as an issue. Links make it really easy to add context to a piece of text. You can add links to references to previous issues, technical terminology that other people not understand, and informational blog posts. These links help balance out the context so that those reading comments you write have a better understand of your intention and meaning.

Emojis are also your best friend

Communicating on the Internet can be difficult. A picture is worth a thousand words and that’s why emojis exist. Emojis (and GIFs for that matter) help add a layer of emotion. Sarcasm, humor, sadness, and disappointment are all feelings that are complex to express with just words.

And that’s it! The focus for a successful discussion on a project’s issue board is all about making sure that everyone is well-informed from an intellectual and emotional perspective. If everyone has a pretty good idea of what everyone is thinking and feeling, it’s a little more likely that your project’s issue board will be a happy place to be.