Open source contribution: Open API validator

I wonder if others experience the same rush of excitement that I do when I discover a bug in an open source package? Spotting an opportunity to contribute an improvement is novel and exciting. I anticipate my pull-request being welcomed with great enthusiasm, celebrated and immediately merged... but that's rarely what happens.

For example take my recent PR to the /thephpleague/openapi-psr7-validator. It was back in January that I discovered the bug when I noticed some schema validation did not match the synthetic requests in the tests, and yet the tests were somehow still passing. This was a large API built in Symfony with many hundreds of endpoints, several of which were very similar with only subtle variations.

Timeline

I forked the repo, wrote the patch complete with test coverage and raised my PR on 31 January. Our problem at work could now be resolved by pointing Composer to use my fork, but my PR wouldn't get merged for nearly 2 months.

The PR received no activity for the first 2 weeks so I breathed some life back into it with a comment. Another 9 days of no engagement and then sadly, on 22 February a disrupter entered the chat.

The PR became a victim of the kind of slowdown that happens when an outside observer used it as a platform to write a "thinking out loud" style comment. The kind of suggestion that appears relevant at first, but is in fact unrelated. The unresolved thread created the illusion that an important discussion must conclude before the PR could be merged, meaning the person with the power to merge held off. But the unrelated nature of the discussion meant there was no action that I could do to resolve it.

In the end it took weeks of gentle nudging until on 23 March I finally managed to coax the commenter into admitting he knew of no reason to block it from being merged. After which it took just hours to get it merged. The whole slowdown was compounded by the limited time the package maintainer could spare to review this increasingly confusing non-discussion.

Conclusions

Contributing to an open source project is predominantly a social skill, writing the code is a minor part. Prepare yourself to be a salesman of your solution. People's time is not free.

If you comment on someone else's PR, be aware you have the power to block progress and with that power comes responsibility. I recommended reading https://conventionalcomments.org/ where you label your comment as an issue, suggestion or just a thought.

Package maintainers usually have proper full time jobs. They are busy, which is even more reason to keep the noise to a minimum.