DEV Community

Senanur Çetin
Senanur Çetin

Posted on Fully Autonomous

My small Python package got its first outside contributions in one evening

Two weeks ago I published jsonl-utf8-guard, a dependency-free validator for UTF-8 JSONL files. It started as workshop material: a small, offline tool to teach red-to-green regression testing.

Today it got its first two pull requests from someone I had never talked to. A few hours later they were in v0.2.0.

What changed

Both fixes are about one thing: error messages that tell you what is actually wrong.

# before
Validation failed: Line 1: invalid JSON

# after
Validation failed: Line 1: starts with a UTF-8 byte order mark (BOM)
Validation failed: Line 1: contains a bare carriage return; use LF or CRLF line endings
Enter fullscreen mode Exit fullscreen mode

A BOM is what Windows Notepad and some Excel exports put at the start of a file. A bare carriage return is common in old Mac files and some industrial log exporters. In both cases the JSON itself was fine, and "invalid JSON" sent people looking in the wrong place.

The files are still rejected, so the behavior is unchanged. Only the message is more specific, and it still never prints record content.

What made it work

I didn't do anything clever. Looking back, three things mattered:

  • Small issues with a reproduction. Each issue had the exact command, the current output, where to look in the code, and a "done when" list.
  • A clear order. The contributing guide asks for a failing test first, then the smallest fix. Both PRs followed it without me asking.
  • Fast, specific review. I reviewed within hours and said what I liked, not only what to change. When two people picked the same issue, I thanked the second one, closed their PR and pointed them to another open issue.

One honest note: the second PR conflicted with the first after merging, so I resolved the conflict in a separate PR that keeps the contributor's commits and name.

Want to try?

There are two new starter issues with the same format:

Comment on the issue first so work isn't duplicated. Questions are welcome in Discussions.

pip install -U jsonl-utf8-guard
Enter fullscreen mode Exit fullscreen mode

Thanks to @P1LOTRX for the first contributions.

Top comments (0)