DEV Community: mrick

A Practical Guide to Growing Your Open Source Project: Part 1 – Contributors

mrick — Tue, 10 Aug 2021 01:38:20 +0000

This post originally appeared in my free daily newsletter on startups and engineering.
You can join 200+ subscribers here: https://matt-rickard.com/subscribe/

Open-source is great for engineers. It allows us to share our work and collaborate with people from around the world. But what if nobody else shows up?

Getting traction and growing an open-source project is really, really difficult. I know because I've spent the last few years doing that. I've been an open-source maintainer of minikube (21k stars), skaffold (11.5k stars), kubeflow (10.6k stars), distroless (10.2k stars), and active within the Kubernetes (79k stars) and Docker (60k stars) communities.

I'm going to tell you practical tips that you can use today to bring on more contributors, more users, and to develop a more vibrant community for your open-source project.

These tips are based on my own experience growing open source projects – things that I did that worked, or mistakes I made.

Part one is about growing the contributor base.

Make it dead easy to contribute.

We have a cognitive bias that we like things more if we feel like we had a part in building them (read: The IKEA Effect in Software Development). Despite this cognitive bias, most projects unwillingly make it difficult for outside contributors. Contributor onboarding can't be an afterthought. Here's how to make contributing to your project dead easy.

The build script should be one-step and with minimal dependencies. Complex toolchains and environment dependencies mean friction. For skaffold, the build process was entirely dockerized – new contributors didn't have to spend time setting up their environment. No more of "but it worked on my machine".
The test script should be one-step and be as close as possible to what runs in CI. When the tests pass locally, but CI runs something entirely different, contributors churn. Make sure that the test command is easy to run, something like make test or ./test.sh, and that it runs all the unit, integration, and linting tasks.
Reduce flakes, or false negatives, in CI. The worst feeling is when a contributor painstakingly checks that their code conforms to the project's standards and tests, only to see CI fail miserably. How do they debug that? Nobody wants to debug someone else's CI system.
Accept contributions, even if you have to fix them up later. Onboarding contributors is an exercise in mentorship. You'll have to dedicate time upfront as these users learn the codebase and project style. This takes time. Sometimes, features need to get merged before a pull request can be fully iterated. Pull requests that are open too long become difficult to merge – my law of pull requests – "The longer a pull request has been open, the longer it will take to merge."
Use the "Good First Issue" tag. GitHub actually treats these as special issues, pushing them onto the GitHub feed for higher visibility. Use that to your advantage and craft well-written issues tagged as "good-first-issue". They can be as simple as backlogged bug fixes. But you have to already know how to fix the issue and it has to be contained to a small testable surface, there's a low probability that new contributors will be able to fix deep problems in your project across hundreds of files.
Advanced tip: have a way for approved contributors to re-trigger CI. For example, Kubernetes, Kubeflow, and minikube use a tool called prow to run tests. Prow comes with a prow-bot that can accept different commands, automatically tagging issues or rerunning specific tests. Not for small projects, but this can alleviate maintainer headaches caused by trivial busy work.
Advanced tip: previews using Netlify or Vercel. Especially for documentation and web applications, have previews autogenerated on pull requests. Even if contributors have gone through all the steps, it's great for them and the maintainers to visualize the changes while reviewing. This is great for non-technical contributions, such as verifying documentation changes.

Tomorrow, in Part 2, I'll cover how to build a community for your open source project. Then, on Wednesday, Part 3 will cover the top of the funnel with potential users. If you haven't already, make sure you subscribe so you don't miss new posts every day.

A Surprising Fact From Stack Overflow's Developer Survey

mrick — Wed, 04 Aug 2021 15:11:49 +0000

Every year, Stack Overflow, a question and answer site for developers, runs a survey. It is probably the largest scale data analysis of software engineers.

This year showed some trends that were surprising.

Docker is the fastest-growing tool among developers. In 2020, 35% of respondents said they used Docker. In 2021, 48.85% said they used Docker. If you look at estimates for the total number of developers, they range from 10 to 25 million. That's 1.4 to 3 million new users this year.

For more surprising facts from this year's developer survey, check out my post on Unexpected Developer Trends.

For expert resources on Docker and Kubernetes, check out some of my writing on the state of container technology.

Reflections on 10,000 Hours of Programming

mrick — Tue, 03 Aug 2021 23:00:26 +0000

This post originally appeared in my free daily newsletter on startups and engineering.
You can join 200+ subscribers here: https://matt-rickard.com/subscribe/

The key to achieving world-class expertise in any skill, is to a large extent, a matter of practicing the correct way, for a total of around 10,000 hours — Malcolm Gladwell in Outsiders

Well, I'm certainly not a world-class expert, but I have put my 10,000 hours of deliberate practice into programming. Here are 31 of my reflections on programming.

These are reflections only about pure coding — no lessons sum up to "programming is about people" or "how to be a senior technical leader" (arguably more important to a career, but not the topic of this post).

These reflections are just about deliberately writing code for 10,000 hours. Most don't apply to beginners. These reflections are not career advice. Think of them as lessons on being a technical guitarist, not about being a good band member. They are about becoming a better programmer for yourself.

Browsing the source is almost always faster than finding an answer on StackOverflow.
In many cases, what you're working on doesn't have an answer on the internet. That usually means the problem is hard or important, or both.
Delete as much code as you can.
Syntactic sugar is usually bad.
Simple is hard.
Have a wide variety of tools and know which ones to use for the job.
Know the internals of the most used ones like git and bash (I can get out of the most gnarly git rebase or merge).
Build your own tools for repeated workflows. There is nothing faster than using a tool you made yourself (see: software I wrote.)
Only learn from the best. So when I was learning Go, I read the standard library.
If it looks ugly, it is most likely a terrible mistake.
If you have to write a comment that isn't a docstring, it should probably be refactored. Every new line of comments increases this probability.
If you don't understand how your program runs in production, you don't understand the program itself. In my experience, the best engineers know how their program works in every environment.
The above rule applies to the build pipeline as well.
Use other people's code religiously.
Corollary: Most code out there is terrible. Sometimes it's easier to write a better version yourself.
A rough rule of thumb: never take a direct dependency on a small library that you could easily rewrite or a large library that should have been small.
Know when to break the rules. For rules like "don't repeat yourself," sometimes a little repetition is better than a bit of dependency. 18.Organizing your code into modules, packages, and functions is important. Knowing where API boundaries will materialize is an art.
Pick the most efficient tool most of the time, but also pick what you know. Is Arch Linux the most efficient operating system for the modern developer? For me, it is, but for most, probably not. Should you use acme? Only if you're Rob Pike.
Avoid cyclomatic complexity. Novice coders don't even know that they've tangled the dependency graph until it's too late.
Avoid nesting conditionals deeply. Have common sense about your conditional tests and naming convention.
Name variables correctly. Again, an art.
While rare, sometimes it's a problem with the compiler. Otherwise, it's always DNS.
Use esoteric language features sparingly, but use them when you're supposed to, for that is the point.
Technology does not diffuse equally. For example, there is a lot that frontend developers could learn from low-level engineers (especially now that everything is compiled). 26. Likewise, there are UX and usability features that JavaScript developers could teach cloud engineers.
As a result, different kinds of engineers look at the world differently.
Some programmers are 10x more efficient than others. I know because I've been both a 10x programmer and a -1x programmer.
There's no correlation between being a 10x programmer and a 10x employee (maybe a negative one).
Good APIs are easy to use and hard to misuse. The configuration cycle goes from hardcoded values to environment variables, to CLI flags, to a configuration file, to a templated configuration file, to a DSL, to a generic bash script, and back to hardcoded values. Know where you are on this Heptagon of Configuration.
All layers of abstraction are malleable. If you run into a fundamental wall, sometimes the answer is to go down a layer of abstraction. You aren't confined to the surface.

Where did I put in my 10,000 hours? Well, I've been programming for about 15 years. Most recently, I worked as a professional software engineer at Google on Kubernetes and Blackstone, the private equity firm. Before that, I spent most of college in the library writing programs for my own projects instead of writing proofs (which I should have been doing as a math major). And before that, I was hacking away at all sorts of things — running a botnet on RuneScape, writing a Latin translation app for the iPhone (so I could do better on my Latin exams), creating a web clipper, or ricing up my desktop.

What did I do for the 10,000 hours? The most recent work was in distributed systems, but I've written code across the stack. Languages like PHP, JavaScript, Go, Ruby, Python, C#, Java, Swift. Frontend, backend, mobile, kernel, cloud, ops, and even some IT. I've worked on large-scale open-source projects like Kubernetes and maintained subprojects, which allowed me to have my code peer-reviewed by some of the best engineers.

Service Reliability Math That Every Engineer Should Know

mrick — Sun, 13 Jun 2021 19:52:19 +0000