Companies like Stoplight stand on the shoulders of giants, by combining existing open-source tooling, built around freely available open standards, to produce a combination of open and closed source code. We don’t want to just take from open-source, we want to support the projects we use, and there are three main ways that companies can do that.
Why? Well, other than being the right thing to do, not supporting projects can lead to them going unmaintained. This happens for a whole variety of reasons, including burnout, amongst other things. We don’t want anyone suffering from that, but even if the feelings of strangers on the internet don’t motivate you, consider what you will do if that project shuts down. Rewriting a bunch of code, or having to build your own replacement, can take a lot of time and money out of your hands that could be spent on working on your core business.
Whether you pick altruism or self-preservation, the solutions to supporting open-source projects remain very much the same.
Open-source projects are a lot of work. Some projects are maintained by companies that have an income stream already. Many more are managed by volunteers in their spare time. Giving them money for their work - especially when it’s something you make money from - makes sense.
At Stoplight, we are constructing a list of projects which matter to us, and figuring out how we can pay them an appropriate amount.
Sometimes I bribe people to merge my PR by clicking the “Buy me a coffee” button. This is small stuff, but it’s appreciated a little, I’m sure. For massively important projects like JSON Schema, we set up monthly donations, which helps them cover admin fees, domain costs, email hosting, whatever it is they gotta pay for, including a part-time stipend if they want. Whatever keeps the project running smoothly, it’s up to them.
Sometimes project contributions can become enough that the contributors stop doing things on the side, and turn it into a day job. This has rarely (if ever) been bad for a community.
If you need help figuring out which projects you can fund, and you’re using npm, you can type
We had one developer using Spectral at their day job, and like many others in that position, they were reporting bugs and requesting features. Unlike many, they were also contributing pull requests, and not just that but were updating documentation as they did it, tidying up the codebase as they want, and just being awesome.
There would have been an argument for letting them just keep going (essentially having their day-job pick up a bit of our developer payroll!), but we decided instead to contract that developer part-time.
If you ever need to hire new developers, looking at your GitHub contributor list is an excellent place to start. After all, you know they know the codebase, you know they are passionate about the domain, so if they’re up for it: welcome aboard!
There are a lot of ways companies can give time to open-source projects, but I’m gonna talk about a few we’ve done here at Stoplight.
We used to maintain a lot of our own forks, but over the last year, we’ve gone on an upstreaming expedition.
Doing this, we managed to axe a bunch of repos from our organization, taking us from 240 (😱) down to 197 (😅). More work to be done.
If you need a sales pitch to get your boss to approve this, and “it’s the right thing to do” isn’t landing, you can explain that your team will no longer have to maintain these forks. Keeping an in-house fork up-to-date with features, security patches, possible conflicts, etc. is a time suck.
Getting your changes accepted and merged seems like it will take a long time, but one of those PRs to JSON Schema Faker was merged in 6 hours, and a new release was tagged minutes later.
On the rare occasion that the maintainer flatly refuses your change, and no amount of reasoning or cooperation will solve the disagreement… well, you have some options. If the project is some sort of library and your change is mostly a convenience method, you could just abstract that library a little, and add the convenience method to your layer instead. If it is more fundamental than that, and you know it’s a good change, then that’s what forks are for! Come up with a new name, make a sweet logo, do the whole thing, and publish that fork under your company name. Make them wish they’d accepted it! 😋
Thanks to Stoplight giving me time to get on the OpenAPI TSC calls, various cool things have happened, like us finally getting OpenAPI v3.1 to use proper JSON Schema.
Us tooling vendors have a crucial role in standards bodies like OpenAPI, as somebody needs to try implementing proposed new functionality to see if it’s any good.
Recently we tried out the Alternative Schemas proposal, and it did not go too well. It would have been almost impossible for us to implement and would have provided very little value. After we shared our feedback, the group focused efforts on the OpenAPI == JSON Schema resolution, which did solve the problems for our users, and does have a very clear path to implementation.
Nothing is better for fostering a thriving open-source community than welcome contributions from first-timers. They could be new to open-source in general, new to the language/framework your projects are in, or new to your projects. Maybe these users need help sending pull requests, running the test suite, understanding test output, solving conflicts, etc.
Whatever type of new they are, if your maintainers can spend a little time ramping these new contributors up, you can benefit along with the whole open-source community.
I’m not suggesting heroic efforts here, a lot of the time it is just a case of pleasantly pointing folks to a blog post, or Git guide. Some maintainers can get grumpy, even hostile, but if your company can teach patience as a virtue, you’ll see growth in contributions, and occasionally get lovely feedback like this.
You can give people and projects a shout-out in a Thanks section of the readme.
For example, in Spectral, we talk about some of the people who did awesome work.
If you can’t spare the money, this is the least you can do.
Open-source is hard work. A lot of people get stuck in situations where they no longer use something they’ve open-sourced, and are stuck maintaining it with hordes of people making demands on their time.
Best Practices for Designing and Developing RESTful APIs
Feb 25, 2020
We asked four API experts how they approach API governance, internal discovery, and the entire API lifecycle.
Feb 20, 2020