What I Learned Trying to Write Better GitHub Issues for Open-Source Contributors

georgetoloraia — Tue, 30 Dec 2025 15:03:27 +0000

Maintaining an open-source project taught me something I didn’t expect:
writing good GitHub issues is a skill of its own.

Early on, I assumed that if an issue made sense to me, it would make sense to contributors. In practice, that’s rarely true. Contributors see issues with fresh eyes, limited context, and very little patience for ambiguity.

Recently, I started deliberately improving how I write issues and asking myself a simple question:

If I were a contributor seeing this issue for the first time, would I know where to start?

Here are a few lessons that helped me improve issue clarity and make them more contributor-friendly.

Why issue quality matters more than you think

From a contributor’s perspective, an issue is often evaluated in under a minute.

They scan for:

Is the problem clearly stated?
Is the scope reasonable?
Is it obvious what “done” means?
Can I tell which part of the codebase this touches?

If any of those are unclear, many contributors simply move on — even if they like the project.

From the maintainer side, unclear issues lead to:

long comment threads clarifying intent
mismatched expectations
abandoned PRs

Clear issues save time on both sides.

What I changed in how I write issues
1. Separate context from task

I now structure issues so contributors can quickly find the actionable part.

A typical flow:

Problem / Current State
Why this matters
What needs to change
Acceptance criteria

This lets readers skim intelligently instead of reading a wall of text.

2. Make “done” explicit

One of the biggest improvements was spelling out acceptance criteria.

Instead of:

“Clean up the payout pipeline”

I aim for:

legacy paths removed
one canonical flow remains
tests updated
no behavior regression

Contributors shouldn’t have to guess when the task is complete.

3. Avoid assuming codebase familiarity

Even experienced developers are new to your code.

Helpful additions:

naming the relevant modules
mentioning entry points
pointing to existing commands or tests

This lowers the mental cost of starting.

A concrete example

Here’s one issue I wrote after applying these ideas:

👉 https://github.com/georgetoloraia/selflink-backend/issues/20

I’m not sharing this as a request for fixes — just as a real example of how I try to:

describe the current state
explain the goal
define acceptance criteria
reduce ambiguity for contributors

If you maintain OSS projects, you’ve probably seen (or written) issues that could benefit from this kind of structure.

Closing thoughts

I’m still learning how to do this well, but being more intentional about issue writing has already:

made it easier for contributors to engage

If you maintain open-source projects, I’d be curious:

What makes a GitHub issue feel actionable to you?
And what’s the most common mistake you see maintainers make?

I’m working on an open-source backend built with Django, ASGI (WebSockets), PostgreSQL, and a small containerized setup.

georgetoloraia — Tue, 23 Dec 2025 04:21:13 +0000

Keep HTTP and real-time separate

Django is excellent for HTTP APIs. ASGI is great for WebSockets. Mixing them too early adds unnecessary complexity.

What worked well:

WSGI (gunicorn) for standard API endpoints
ASGI (uvicorn) only for real-time features
Clear boundaries between sync and async code

This made debugging and scaling much easier.

Don’t rely on runserver

Using Django’s dev server behind proxies or tunnels caused connection resets and unpredictable behavior.

Switching early to gunicorn + uvicorn stabilized everything. Even for early-stage projects, using production servers early is worth it.

Media handling should be isolated

Once users upload files, media quickly becomes an infrastructure concern.

Separating media into a dedicated service (nginx or object storage) reduced app load and removed an entire class of bugs.

Add PgBouncer before you “need” it

With API, ASGI, and workers running, PostgreSQL connections grow fast.

PgBouncer:

Prevented connection exhaustion
Made traffic spikes predictable
Simplified debugging

Transaction pooling with short-lived connections worked best.

Open source needs clarity more than polish

Clear README, honest tradeoffs, and a few beginner-friendly issues attracted more meaningful contributions than perfect code.

Final thought: keep the backend boring, isolate complexity, and optimize for contributors early.

DEV Community: georgetoloraia

What I Learned Trying to Write Better GitHub Issues for Open-Source Contributors

A concrete example

Closing thoughts

I’m working on an open-source backend built with Django, ASGI (WebSockets), PostgreSQL, and a small containerized setup.