I work with Python and Flask a lot to create APIs. A convenient way to document and validate this API is using Flasgger, which is, in their own words:
Easy OpenAPI specs and Swagger UI for your Flask API
Recently I was working on a
POST endpoint which created a resource based on
the data sent in the payload. Ideally, this resource would be created by a
front-end on page load, with default field values if no data was sent.
But Flasgger did not allow sending falsey payloads such as
I thought, maybe, this was an HTTP standard and that I might have to redesign the API with this constraint in mind. So I did some digging. I found out from IETF HTTP that nothing in the HTTP protocol states that the request bodies should be non-empty.
Because I had previously encountered this issue, I decided I would take some time to explore the Flasgger source code and see if I could figure out where empty payloads were being disallowed. Turns out I could fix it with just a few lines of code and a kwargs to allow for backwards-compatible usage.
But a few days later, a maintainer replied:
Maybe it’s best to put the new keyword argument at the end so that current uses passing positional arguments are not affected.
Cool! Even though the PR was not fully working, I promptly edited the code based on the review, and a few hours later, they had merged my Pull Request.
How to contribute
I learnt a few things from this unexpected experience. Here’s how I think you can contribute to open source code you use.
Find a problem
If you’re a programmer, you will most definitely come across limitations or bugs with libraries you use. Sometimes you’ll scream “Why doesn’t this do …!” at your screen. Become aware of these moments and write them down.
Look at the source
Once you find a bug or feature that bothers you, explore the library’s source code and find the general area of code which triggers the behaviour you don’t like.
Then ask yourself these questions:
- Can you fix it easily and elegantly?
- Will your fix mean the library is no longer backwards-compatible?
- How much time will it take you?
If you answer favourably to the above, you have a candidate. Go for it.
Make sure you read the library’s Contributor Code of Conduct. Most open source projects have one. If not, at least make sure you submit an Issue first, clearly outlining the problem and justifying why the fix is needed for more people than just you. Then, submit a Pull Request with your fix and reference the Issue you created.
After this, just wait. Open source software is usually maintained by volunteers who aren’t paid to work on this. Therefore they are managing these projects in their spare time. It could take months before a reply. I suggest looking at other Issues in the repository and gauging how responsive the maintainers are, and set your expectations based on this.
Odds are you’ll get feedback, criticism (sometimes harsh!), and sometimes, your contribution will get rejected.
If that happens even after a back and forth, and improvements to your PR, move on. There are plenty of other projects in need of contribution.
Contributing to open source is a good way to give back to the community. If you’re looking to improve your coding style and best practices, looking at industry-standard libraries will no doubt help.
So give it a go, and eventually, you’ll do it. And I can tell you it feels awesome.