Whether maintainer, user, or BDFL, we're all temporary citizens of one OSS community or another. There's often friction or disagreement within our ranks and calls for rules of conduct, but often less explicit guidance on how to behave in the proper way.
There are some principles that I find make everyone happier:
- Don't discourage others: reject proposals you don't rate, be opinionated, have high standards. Don't make someone feel incompetent for making mistakes or unwelcome for suggesting them. Overlooking a linter or being unfamiliar with a new repo's conventions isn't a character flaw.
- Don't throw your weight around: don't lecture, or demand. If you're insisting, be polite.
- Being polite works wonders in inciting others to cooperate with you. Being rude can discourage someone from contributing to your project or from participating in your ecosystem altogether.
- Be confident not defensive: state your case clearly and completely. Show how your work meets requirements, and invite others to test where it might not. Like a proof, your reasoning is only sound if others can't poke holes in it.
I think most of all this last one is key. When responding to reviews, you're demonstrating your reasoning to a colleague, not defending territory. Even if from personal attachment you feel criticised, or worry your efforts may go to waste, or your path has become obstructed, treat it as collaborative verification. That is, as logical exposition to be verified for coherence, not as testimony to be taken on belief.
What Makes OSS Different
- Asynchronous communication: discussions need to be solution-oriented. The longer they drag on, the more people lose context, drift away, or see their needs change (a new job, a different tech stack). Drawn-out back-and-forth can itself become the blocker, wasting the narrow window when someone is motivated to contribute.
- Public, permanent record: everything is searchable, quotable, and often serves as a project's living documentation (like FAQs). Future contributors-turned-historians may lean on these to understand the design, and any departure from constructive discussion adds noise that they have to filter out.
- Flat hierarchies: maintainers typically act as peers and expect contributors to show autonomy, not wait for direction. The only deference shown is procedural (e.g. to a maintainer merging code), not hierarchical like in a company. You don't pull rank to get your way, nor go over maintainers' heads when you disagree with their call. Everyone negotiates ideas as equals.
- Pull-based and opt-in: work isn't assigned top-down. Contributors self-select from a pool of issues and ideas based on what they believe is necessary or valuable, and in the course of that they might have to negotiate this with others. Conversely, they can also walk away if discouraged, or invest more effort if they feel respected.
- High-stakes language: code alone isn't enough. Specs arrive in natural language, so what gets built depends on how well you articulate what's needed and why. Multiple solutions usually exist; negotiation will determine which one ultimately ships.
- Reduced bandwidth: requires high intentionality. The medium strips away context, so your words must carry more clarity and care.
How you handle disagreement gets noticed. People see whether you're defusing tension or escalating it, arguing fairly or trying to pull rank. That has knock-on effects: if someone criticises my work in a way that feels diminishing, I'm less likely to contribute again; if there's infighting, I'll tread lightly. On the flip side, when projects make a deliberate effort to be kind to newcomers, it's immediately noticeable and encourages further contribution. Even practical factors—like timely reviews or a sense that effort won't be wasted—shape where people choose to spend their time. Most figure this out empirically, through trial and error, or observation. Whether others support your work can directly determine how effectively you achieve your goals, whether it's getting code merged or having your ideas taken seriously.
Express Yourself! No Not Like That
The general theme here is that authority flows from the spec. I believe most good comms comes from how new info is handled, especially negatively polarised news (as in "don't shoot the messenger"). This is why maintainers encourage bug reporting: the users' bad news is their good news, as bugs give an opportunity to become correct, even if only in a small way.
The wrong way to accept bad news is 'performative' or feigned listening exercise. As in, "I hear you, I'm listening" [but using this acknowledgement to effectively ignore the report].
- Do Avoid talking past one another. Directly cite/respond to what people say to get on the same page, but cite to align, not to trap (as in "by your own logic"). Use their words to build shared understanding, not set up contradictions. Quoting someone's terms in an "if-then" construction can read like sarcastic air quotes. "You mentioned predictability of X, here's how Y behaves for comparison..." explores their point, while "So if 'predictably' means behaving like X, then no, Y was not." uses it as a gotcha phrased with an air of finality.
- Do Consider how what you say will land. Anticipate that others may not be regulating their emotions optimally, and may be responding from frustration, fatigue, or lack of context (or are using tools like LLMs that may oversimplify or echo opinions without reasoning through a dialogue in a balanced way).
Here are some examples of rephrasings based on emotional impact:
- Combative? Be neutral. Technical disagreement is not a personal attack. Even if something feels sharp, don't match the energy. Likewise if there's open conflict among others, make it clear you are not picking sides and are maintaining a #GoodVibesOnly environment. Even people in the midst of aggro will respect others' wish to keep it pushing.
- Confrontational/Accusatory? Critique artifacts, not motives. Assume good faith, even when you disagree.
- Dismissive/Condescending? Educate (clarify) rather than focus on correcting ignorance.
- Defensive? Argue from necessity, not preference (feeling attacked = feeling attached!). Lift the argument to the spec level—the requirements that drive the implementation—not the implementation itself. If someone takes issue with your feature, don't defend your specific implementation as "better." Instead, discuss what the spec should be. Once you agree on requirements, implementations either satisfy them or they don't. This shifts the frame from "my way vs. your way" to "our way vs. the requirement."
How to Structure
- State your position clearly. Write to convey what you know, cite the requirements you're acting on (e.g. issues), make an effort to follow technical etiquette, and back up technical claims with sources or demos. Hide extraneous details in
<details>code blocks, avoid overloading others. Be proactive without being presumptuous. - Be comfortable with uncertainty. Don't force things to 'come to a head' prematurely. When you're uncomfortable with ambiguity, it's tempting to use conclusive language, call on ultimatums, or declare routes as dead ends to create a sense of resolution (or "jumping to conclusions"), but this shuts down dialogue and makes people defensive rather than actually resolving anything together. Even when you're confident, leave room for discussion rather than presenting your point as the final word.
- End with action, and keep things actionable. State what you'll do next, ask a specific question (but don't ask things 'for effect'!) If not ending on an action, end on a summary of your view if it adds a useful recap (not if it's just repeating itself). Sometimes a concluding summary can compress detail, making an idea intuitive and allowing others to check that they agree on the overall idea, if not having followed all the details, or allowing their minds to react specifically to a caveat they may hold with the general idea.
Speak Softly and Carry A Clear Spec
When making a point, you can clarify your reasoning by softening language to mark it as subjective ("I think this approach handles edge cases better") or neutralising by grounding it in objective criteria ("This approach handles edge cases that the spec requires").
Softening acknowledges something is your view, signalling an openness to discussion. Neutralising lifts the discussion from personal preference to shared requirements—typically less testy and easier to align on.
This shift often exposes when you're in the wrong frame: if you're stating a personal perspective where you should be citing evidence, the reframing drives you to substantiate rather than merely assert. This naturally helps you lead others to the position you've reached in a way that can be scrutinised and independently verified, rather than asking them to take your word on it.
There are times for both softeners and neutralisers. Saying you think/see/notice phrases your statement as an informed opinion, and should naturally lead you to verify any assertions (if you don't, expect others to).
It's sometimes said that language like this shows indecisiveness and makes one look wishy-washy. I'd suggest it instead adds authority because you're not overselling or dogmatic. You're providing a considered view while acknowledging you could be wrong (and not mistaking yours for the word of God).
Time and place
We need to take on tone appropriate to the setting:
- Deferential and open-minded when proposing ideas others must agree to/contribute towards.
- Confident, leader-like, once tasked with execution.
- Self-assured and a closer: don't ask permission when you have approval/consensus (i.e. don't self-doubt and backtrack too easily in flight). This mainly applies to the closing act of a message, whether your action is closed or open to input. After consensus, new objections need to be specific about what must change and why. Don't let vague concerns restart deliberation (this is how bikeshedding happens). Acknowledge them, document if useful, but keep moving forward.
That's what being a model OSSizen is all about: keeping things moving, keeping things constructive, and above all keep shipping. See you out there. 🚢