Paolo

I maintain a Python download manager. A week ago it had 1,500 stars and zero outside contributors. Today it has nine people with merged pull requests. Nothing about the code changed to cause that — what changed was the issue tracker, and I think the specific things I got wrong are more useful than the things I got right.

Issues that say what to touch
My first "good first issue" said the equivalent of "add tests." Nobody took it. The ones people actually take name the file, the function, the acceptance criteria, and — this turned out to matter most — whether it needs my OS. My project is Windows-only to run, but almost none of the open work requires Windows, and saying so per-issue unblocked most of the queue.

One big cleanup, cut into slices
I had 30 near-identical changes across three files. As one issue it sat there for weeks; nobody wants to sign up for 30 of anything. Split into four labelled slices with line ranges, three got claimed within a day.

Two things went wrong when I did it. I undercounted one file by seven. And my line ranges accidentally left one item outside every slice, so nobody could ever have claimed it. Both were caught only because I recounted against the source instead of trusting my own issue.

A roadmap issue, pinned
One page listing everything open, ranked by size and by whether it needs the OS. It is the single most-visited thing in the repo.

I had also pinned two issues that were already closed, quietly wasting two of the three slots. Check yours.

Correct yourself in public
I have posted several corrections to my own issues now, with the wrong numbers and the right ones. It feels bad and it works: the best pull request I merged came from someone who fixed an error in the issue that spawned it, and said so.

If contributors think your issue text is authoritative, they will implement your mistake.

Read the diff, not the description
A pull request arrived listing three improvements. The diff contained none of them, plus an empty test file. The author was not being dishonest — they had described what they set out to do. I now check every bullet against the actual changes before merging, and I say in CONTRIBUTING.md that I do.

Using your own software finds more than reading it
I audited nearly 5,000 lines and found one real bug. Then I spent an hour actually running the thing and found eight, including a speed readout that was displaying roughly nine times the real rate — provable by comparing what the screen said against the run's own log file.

Every one of those became an issue with a measurement in it, so a contributor can check their fix against a number instead of a feeling. Four of the five people who showed up that afternoon took one of them.

The thing I did not expect
In July I merged eighteen one-line pull requests from accounts created that same week. They looked like real contributions. They were contribution farming — the same accounts had single trivial PRs in Stripe, DataDog and Microsoft repos.

I merged them in good faith and they are now permanently in my history. If you maintain anything with the hacktoberfest topic, October is when this arrives. Write down what counts as a contribution before then, not after.

What I would do differently
Start with the roadmap page, not the issues. Say whether each thing needs your OS. Cut the big cleanups into named slices before anyone asks. And run your own software for an hour before you write a single issue from reading the code.

Happy to answer questions about any of it, including the parts that did not work.