I’ve been using Kubernetes for a while now and decided it was time to be a responsible open-source citizen, and contribute some code. So I started combing their issue tracker, looking for a relatively small and straight-forward patch that I could cut my teeth on. If you're also thinking of contributing to Kubernetes, I hope you can learn something from my experience.
First Steps
If you, too, have been looking to make your first-ever open-source contribution, GitHub makes it easy to take the all-important first step of finding a beginner-friendly contributing opportunity. Look for issues marked good first issue or help wanted, and don’t forget to look at other projects in the Kubernetes organization.
If you’re still not sure how you can start contributing to Kubernetes, you can glean a lot of insight from a project’s test suite. Writing tests for existing functionality can help you find your bearings in a new codebase, and the maintainers will love you for it. Another option with a fairly low barrier to entry is contributing to Kubernetes documentation — there is even a whole website devoted to helping you get started doing just this. Again, the maintainers will love you for it.
In my case, I found an issue looking to add tests to ensure protobuf doesn’t break their API. That way, the maintainers can upgrade the protobuf dependency as needed without triggering any unpleasant surprises. A nice side effect of choosing this issue, in particular, was learning more about protobuf. Prior to starting, I knew what protobuf was, and even how to use it, but I had no idea how it actually worked. Protobuf internals are beyond the scope of this article, so here’s a link to a comprehensive overview.
Diving In
Once I decided what issue I was going to work on, I cloned the repo and started looking through the code. Kubernetes, for better or for worse, contains nearly 4,000,000 lines of code spread out across more than 13,000 files. Navigating a codebase this large can be daunting, to say the least, so diving in without a plan is definitely not advised.
One thing that can greatly narrow your search domain is identifying which packages or libraries you’ll need to dig into to accomplish your goals. My patch, for example, targets the apimachinery library. That cuts it down to around 60kloc across ~330 files. Now we’re getting somewhere!
Once you know where to look, a good understanding of how to search the source with tools like find and ack will be an invaluable asset, so it pays to brush up on their usage (the Linux man pages are a great place to start). You should ultimately be able to focus your attention on, at most, a handful of files.
Do Your Thing
The next step is to actually write your code. In my case, that meant adding a few tests to an existing file. If your patch is much larger in scope, then you should probably put it on hold, and find something smaller. It’s no fun to spend weeks writing something you’re proud of, only to have it rejected right off the bat.
I can’t provide much more guidance when it comes to writing your first patch, since every issue is unique. Hopefully, you didn’t bite off more than you could chew. Once you’re happy with your code and/or documentation, it’s time to submit your pull request. That can be a rather stressful experience for the uninitiated, and if you’re not used to very direct feedback, it can be hurt. Try not to take things too personally.
To minimise the pain, it’s a good idea to make sure your contribution is consistent with the existing codebase, and/or Documentation Style Guide. Also, make sure your git history is clean, by squashing and rebasing your working commits and checking the diffs against the latest master.
Read The Fine Print
Before your patch can be reviewed, you will have to sign the CNCF Contributor License Agreement, which grants the Cloud Native Computing Foundation additional rights and limitations not covered under the Apache-2.0 license that accompanies the project. While the CLA requirement definitely merits further discussion, this article is not the place to do it.
Once you’ve signed the CLA, make sure you read and follow the pull request template. In the same vein, you should pay special attention to the format and content of your commit message. Make sure that the message is clear and concise, and that it conveys the purpose of your changes/additions. If you’re not sure what format to use, I’m quite fond of:
`topic: subtopic: Concise description of your patch here`
For example, the commit message for my patch was:
`apimachinery: protobuf: Test protobuf compatibility`
Wait For It...
Now comes the hard part: waiting for review. Kubernetes is one of the most active projects on GitHub, and currently has over 1,000 open pull requests, so it shouldn’t come as a surprise that you might have to wait a while before you get any feedback.
First, someone from the Kubernetes organisation will triage your patch, and assign it to a suitable reviewer. If that person deems it safe, they will trigger the tests and review your code for style, correctness, and utility. You will probably need to make some changes, unless your patch is tiny and you’re a rock star. Finally, once they’re happy with your patch, they’ll flag it with a ‘/LGTM’ message, and it will be automatically merged into Kubernetes’ master branch.
Congratulations, you’re now part of the CNCF/Kubernetes developer community! That wasn’t so bad, was it? Feel free to share your thoughts in the comments below, and ping me here or on Twitter if you have any questions or comments.
Feature photo by Maximilian Weisbecker on Unsplash
Want to learn more about Kubernetes? Check out our training course below:
Previous article
