In 2017 I made a few small pull requests to Phaser, a wonderful and popular JS game framework. Personally, I really enjoy the challenge of opening concise, well explained pull requests. It’s not always easy and even the best hackers will end up writing PR descriptions that are sorely lacking. When it’s a library or framework where search engines are likely to send new programmers (or programmers new to the language/tool), however, the stakes are much higher.

I tend to jump to the source of a tool pretty quickly if the docs don’t immediately answer my question. When you think you’ve found a pull request that introduced or fixed a bug you’re wrestling with, it can be disappointing when the PR descriptions, comments, and commit messages aren’t clear. Understanding the changes may require more digging, jumping to cross-referenced issues and discussions. Even with a lot of programming under my belt, it’s easy to bump into a pull request three or four times before realizing it’s actually what you’re looking for. This sort of thing can be really tough on new developers. It isn’t a great example to set and also obfuscates what might have been educational.

As with much of software development, the solution isn’t particularly difficult, it’s just time-consuming. On this pull request to Phaser CE, I ended up spending more time writing a PR description and building an example that demonstrated the changes clearly than I spent on the actual PR. The description is full of terms that someone might conceivably search for without knowing that the feature exists. The demo’s sprite sheets and code and the screenshots quickly indicate the use case. I probably could have gotten this merged with a fraction of the prose and with a much messier demo, since the maintainers would know what I was getting at. But the community is bigger than the core maintainers of a project and the effort is worth it.