Intro to Open Source - Lesson 4 - What You Should Learn Before Contributing Code (Hint: it’s not much!)
In this lesson we are going to discuss what you need to learn before you contribute code! In the previous lesson, we talked about all the different types of contributions you could make, and we told you that for code contributions specifically, you would need to know some prerequisites.
The good news is that there aren’t many prerequisites, and there is a plethora of resources online for all of these. Since these topics are quite broad, and the specifics will change from project to project, we will not be going into depth about each topic. Rather we will give an overview of what you should know, and provide you with some links to where you can find out more.
Set up a development environment
To develop on any project, you will need a working development environment. What do we mean by that? A development environment is a place where you can modify and examine code without affecting the currently released code. Your development environment will be what you use to make all of your code changes, so you want to make sure that it works well.
In this article, we will provide you with some basics that will help you with setting up your development environment. However, since we do not know which project you will be contributing to, we will not be able to provide you with specifics. Luckily, most projects have specific information on how to set up your environment, so you won’t be without resources to help you!
First of all, most set-up instructions will be asking you to run commands through some form of shell or terminal. Well, a shell is a textual wrapper of underlying operating system utilities, along with other tools and programs. You can learn more about what a shell is here. Generally speaking, your computer will have a shell installed on it already although you can easily find instructions to install a different shell on your favorite search engine. For Macbooks this will likely be zsh, whereas for Linux this will likely be bash, and for Windows it will be Powershell.
For basic commands, these act the same although Powershell in particular has a different set of commands than bash and zsh. Since most scripts are written in bash, we recommend using one of bash or zsh. The shell is one of the most powerful tools on your computer, so learn how to use it well. A great starter guide can be found here.
One of the basic tools you will need on any system where you want to develop software is git. You will use git to keep track of all of the changes you make to the code, as well as to download a local copy of the code to your system in order to make your changes. To install git onto your system, you can follow these instructions. If you are on windows, this will also install git bash, which will give you a bash shell to use. We highly recommend using this instead of Powershell. To learn more about how to use git, keep reading - we’ll discuss that in the next section of this lesson.
Another tool which you will want to use is an editor or IDE. IDE stands for Integrated Development Environment, and contains an Editor as well as some extra tools. From now on we will refer to both editors and IDEs as editors for simplicity. There are many different types of editors out there: some of the more “old fashioned” ones are emacs and vim, as well as the newer fork of vim: neovim. While these are very powerful tools, they are not particularly beginner friendly, so we recommend that you use a newer editor instead. The two most common non-vim/emacs editors are VS Code and the JetBrains IDEs. VS Code is more general purpose and has more plugins than JetBrains IDEs, and it is also free. On the flipside, JetBrains IDEs are more powerful and support more features out of the box. They are also language-specific. For example, if you want to program in Go you likely want GoLand, while to program in Java you would want IntelliJ IDEA. While these are paid, there are some free Community Editions available for some of the JetBrains IDEs, and if you are a student you can get a free license to all of the JetBrains IDEs. At the end of the day, it doesn't matter which IDE you choose, as long as you feel comfortable using it.
In addition to these tools, whichever project you work on will have additional dependencies and tools you will need to install to be able to run the code. If you understand the basics of your shell and git, you should be able to install these yourself without too much hassle. However, if this proves to be difficult, you should reach out to the maintainers of the project on whatever communication platform the project uses. You can generally find this information out by looking in the “Community” or “Contributing” sections of the project website or README on GitHub.
Git Basics
Most open source code contribution workflows require the use of git, so you should learn at least the basics of it. Git is a distributed version control system, which means that it allows for the tracking of changes from different contributors on different computers all around the world. Additionally, it does this in a way which is more friendly to coding workflows than a “google docs” type experience. If you would like to learn more about the basics of git, feel free to go through the lessons in https://github.com/Cali0707/git-basics. If you can successfully complete all the practice exercises in those lessons, you will have all the necessary git skills to contribute to open source projects.
Programming Basics
You should know the basics of the programming language that the open source project you are contributing to is written in. So, if you do not yet feel comfortable making basic code changes in the language of your project, we recommend that you learn that first and then attempt to contribute to the project. Open source contributions are a great way to improve your programming skills and knowledge, however you will have a really hard time making any progress on your contribution if you don’t know how to program in the project’s language.
If you have prior knowledge of 1 or more programming languages, the good news is that there are tons of links online to resources to learn to program in various languages, so you can always teach yourself what you need to know. One of the best ways to learn a language is to read the documentation for the language or to read a guide of some kind. Your goal here is to learn the basic syntax of the language and see some examples of how to solve simple problems in the language. From there, working on a small project is likely best, as it will expose you to the intricacies of the language. After your small project is done, or once you are feeling comfortable working in the language, you should be ready to start contributing!
If you have no programming experience, the approach we described above likely won’t work for you as you will also want to learn programming fundamentals. For this, we highly recommend checking out CS50 from Harvard online. The course is free, and covers all of the fundamentals you will need to know. There are also many great resources such as blog posts and youtube tutorials which can teach you these fundamentals as well.
How to ask questions
Throughout the course of your open source journey, there will be many times when you will get stuck. Maybe it will be as you set up your development environment, maybe it will be as you try and make some changes through git, maybe it will be as you are programming your changes or as you are learning a new programming language. Whenever it occurs, you should ask a question and get help, rather than giving up on your open source journey. However, there are a few things you should consider when asking your question to ensure that you get a good response.
First of all, you need to find a good medium to ask your question in. Is it a general programming question? Try StackOverflow, Reddit, or your LLM(Large Language Model) of choice. Is it a question specific to an open source project? Try one of their communication platforms. For example, if your question is about a problem you are facing while setting up your development environment for Knative, asking it in one of the Knative slack channels or on a GitHub issue on a Knative repository would make sense. Similarly, if you are writing some go code for a feature for Knative, and don’t know how to use some language feature, asking that on StackOverflow, Reddit, or ChatGPT would make more sense.
Secondly, you should provide good context to your question. Let people know why you are interested in something, or how you encountered this problem. For example, you can say “while I was working on…, I found …”, and then ask your question. This will help people understand your question better, and give you an answer that is more specific to your actual needs. It is also important to explain what you have done so far to try and solve the problem. This will both help people give you new answers to the problem, rather than what you have already tried and also will make them more likely to answer you. People are often happier to help you when it seems like you have tried to solve the problem yourself, and even though a LLM won’t care, the LLM may be able to give a better answer if it knows what won’t work.
With these two points in mind, you should be able to ask for help when you need it, so combined with the other more technical skills we outlined earlier you are all set to make your first code contributions! For a more detailed explanation of the specifics of contributing code, keep reading the next lesson. We look forward to seeing you there!
