Go from zero to hero in no time!
If you have any sort of interest in software, you’ve probably heard of open source (unless you live under a rock, in which case “rock on” - pun fully intended). But what is open source? Who works on it? How does anyone make money working on it? And how can you get involved?
What is Open Source?
Open source software is software that is freely available, can be used and modified (depending on licensing – more on this later), and can be enhanced for the benefit of the community.
What community, you ask? Well, open source projects typically have a community associated with them made up of users, contributors, peer reviewers, maintainers (people who approve changes and features) and any others with an interest in the project. Some open-source projects are combined under an umbrella organization, such as The Linux Foundation and the Cloud Native Computing Foundation (CNCF), and hold regular conferences to bring community members together to share ideas and network (there’s usually some fun swag as well).
Open source software isn’t as out of reach as it may seem. I’m guessing you’ve heard of at least one of these projects (all open source):
And if none of those ring a bell, surely you’ve scrolled mindlessly through the content catalog on Netflix, which uses the Netflix Conductor workflow engine and is, you guessed it, open source software.
Ok, so open source software is everywhere. But who works on this stuff?
Who Works on It?
The short answer is – lots of people. Some open source contributors work at the company that originally open-sourced a project. Some are users of the software who want to add functionality or fix issues. Some are weekend warriors who just really enjoy being involved with cool tech. There’s something for anyone and everyone.
But If It’s Free....
Here’s the rub: if open source software is freely available, how can individuals or companies make money working on it? The answer is – it depends.
Sometimes technology is not directly related to products that a company sells, but by open sourcing it the company (as well as other companies with an interest) can benefit from open collaboration on the technology.
Sometimes the basic level of functionality for a product is open sourced and there’s a paid tier for either better features and quality or support/maintenance around the project.
And sometimes, a project is open sourced in an act of benevolence to “pay it forward” and enrich technology for the greater good.
As far as individuals go, many have a corporate day job and give a certain amount of time to working on open source (as approved by their company, of course). Some may have the ability to work on open source full-time, depending on company objectives.
Ok, so open source is everywhere, many companies and people work on it, and some manage to make money doing it. But, what’s in it for you?
Why You Should Get Involved
There are many benefits to working on open source projects. Let’s look at a few of them.
One benefit is that it allows you to gain experience and expertise with different technology. Before open source was so popular, technology was mostly privately owned and maintained, which meant the only way to work on it was to work for the company that owned it. But now, technology is at your fingertips, and it transcends any one company. Which leads me to my next point.
Another benefit of working on open source is that your contributions live on outside of your employment, which means that you can cultivate and maintain a reputation in the open source world regardless of where you work. This can be a way to build up a portfolio of work, which is a great resume builder.
And while you’re building up your portfolio, you’re also making amazing connections with other open source contributors. Networking, it’s a thing.
"Collective design and collaboration with the diverse hive mind makes for more robust solutions."
Finally, open source involvement brings with it the benefit of diversity. By working collaboratively with others, you’ll be working with people whose background and experiences are different than your own, and this can be inspiring and life changing. Collective design and collaboration with the diverse hive mind makes for more robust solutions, and we can all benefit from it.
A Quick Note on Licenses
I mentioned above that open source software is freely available and can be used and modified by anyone. This comes with a huge caveat though – the allowed usage of any open source software is governed by the license it uses. There are many different open source licenses currently in use, some more permissive than others. This is a very broad topic, and the interpretation of the nuances of open source licenses is best left to lawyers, but the bottom line is that you need to make sure your usage of any open source software complies with its license.
How To Get Started
Still with me? Excellent, let’s get started!
Terminology
Here’s some basic terminology:
- Git – A tool to manage source code
- GitHub – A development platform (arguably the most popular one) that contains open source code repositories
- Repository – A place where source code, documentation, etc. are stored for a project
- Branch - A snapshot of your code changes for a repository
- Fork – A private copy of a repository existing on a development platform (e.g. GitHub)
- Diff – The difference between either your branch or fork and the main repository (when a diff is pushed to GitHub, it becomes a pull request)
- Pull Request (PR) - Your code changes that are visible in the repository and ready for public review
- Commit – A set of code changes on a branch
- Clone – A copy of a repository on your local machine. Similar to a fork, but a fork exists on the development platform, e.g. GitHub, while a clone is a copy on your machine. To further clarify, you can clone either the main repository or your fork to your local machine, do your work locally, and then push the changes back up, usually to your fork. From there, you create a pull request against the main repository, and if approved, the changes are merged from your fork to the main repo.
- Head – The head of a branch is the latest commit it’s on
As I mentioned, GitHub is the most popular platform for open source projects, so for the rest of this blog, we’ll work with GitHub.
Basic Flow
To try and pull all of this together, let’s talk about the basic flow of a code change. The basic flow of things on GitHub is here.
After you create a GitHub account and install git on your machine, you can do one of two things. If you just want to try out a project and walk through the code, you can clone the main repository for the project to your machine, browse code, build and run it if desired.
If you’re ready to make changes, you can create a fork of the project repo on GitHub, and then clone your fork to your machine. From there, you’d create a branch, make changes and test, then commit the code on that branch.
When ready, you’ll push your commit from your local branch to your fork in GitHub, which will create that branch on your fork. Then you’d create a pull request (diff) against the main repository, which opens your changes up for public comment and approval.
Once approved, your pull request will be merged into the main repository either on the main or master branch at the head of the branch until someone else’s changes are merged (at which point the head moves to the latest commit).
This probably seems like a lot of terminology and steps, but don’t worry - I’ll break things down below.
Install Git
You’ll need to install the git command-line tool locally in order to view open source code, make changes and test. See the instructions here.
Create an Account
In order to access open source code on GitHub, you’ll need to create an account. I highly recommend setting up a strong password and two-factor authentication to keep your account secure. Also, as mentioned above, your open source contributions will live on throughout your career, regardless of where you work, so consider using your personal email for your account.
If you want to use HTTPS with git to access repositories, you’ll need to create a personal access token and provide it when cloning a repository (more on this below).
If you want to instead use SSH with git, you’ll need to create an SSH key locally and add it to your GitHub account.
Find a Project
Now it’s time to decide which project to work on and how to get involved. There are so many projects to choose from, so browse around, read up on projects of interest, and go for it!
Here I’ll use a project that I’ve been focusing on lately as an example: APIClarity.
Project Layout
Most projects in GitHub have a common layout, so let’s take a look at some of the elements.
README File
If you go to APIClarity, the first thing you’ll see is the source code (Figure 1), followed by some documentation at the bottom.
Figure 1 - Source code for APIClarity
The documentation is sourced in the README.md file in the top-level directory (circled in green in Figure 2), which is standard for projects on GitHub. The README file provides some high-level details about the project, and some details on how to try it out or build it if desired.
Figure 2 - APIClarity README.md File
Improving documentation for a project is an easy way to get your feet wet with modifying code, so if you see something in the project README file that you’d like to change, give it a try.
Issues
Any open issues (i.e. bugs or feature requests) from community members can be found in the Issues tab (circled in green in Figure 3).
Figure 3 - Issues Tab
The current list of issues for APIClarity is shown in Figure 4.
Figure 4 - Current APIClarity Issues
This is another easy way to start getting involved in a project. Pick an issue and work on a fix! When you first start out, it can be hard to identify easy bugs to fix (“low hanging fruit” in developer slang), but once you start running the project and getting familiar with it, it will get better.
And of course, if you find any issues while using the project, file them. Try to give as much information as you can and be open to a discussion of the problem. Active community involvement means communication and sharing of feedback and opinions, and hopefully it is delivered with respect and a genuine interest in making a project better. The best open source communities are inclusive, supportive ones.
Pull Requests
The Pull Requests tab (circled in green in Figure 5) for a project lists all of the active changes that community members are proposing. A pull request is filed once the code changes have been tested and are ready for review.
Figure 5 - Pull Requests Tab
A pull request requires code reviews, and this is another easy way to start getting involved. Review an open pull request, do your best to understand the changes, and provide constructive feedback. I’ll reiterate an earlier point:
“The best open source communities are inclusive, supportive ones.”
Remember, if one of your goals in working on open source software is to establish a reputation in the community, let it be a good one.
The current list of pull requests for APIClarity is shown in Figure 6.
Figure 6 - Current APIClarity Pull Requests
GitHub Stars
In GitHub, you can “star” a repository to indicate your interest in the project, show appreciation to the community, and save off projects of interest. GitHub stars are shown on the main project page (shown in Figure 7 below).
Figure 7 - GitHub Stars for a Project
You can find your starred projects by clicking on your account and going to “Your stars.”
GitHub stars can be used as a metric to indicate how popular a project is. So, if you find a project useful and want it to stick around, giving the project a star is an easy way to show support and give some love to the community.
License
A project repository typically has a license file at the top-level indicating which license the code falls under. See here for an example license file.
Contributors Guide
A project repository should also have a contributors’ guide, which can help you get started on project development and understanding expectations. See here for an example contributors guide.
Code of Conduct
Many projects also include a code of conduct to ensure community interactions remain constructive and inclusive. See here for an example code of conduct.
Clone the Repository
To start out, if you want to walk through the code and start learning the layout, you can directly clone the repository to your local machine.
First, navigate to a directory on your local machine where you’d like to put the source code.
Then, on the main project page under the Code button (Figure 8), select HTTPS or SSH and copy the syntax into your terminal window for the git clone command.
Figure 8 - Select Code Button to Clone Repository
For example, for APIClarity, the HTTPS command is:
git clone https://github.com/openclarity/apiclarity.git
This will pull down the APIClarity code onto your local machine. If you’re using HTTPS to clone the repo, you’ll need to provide your username and the personal access token you created earlier.
A quick suggestion – the easiest way to view large source code projects is to use what’s called an Integrated Development Environment, or IDE, on your local machine. An IDE uses indexing to quickly search the directory structures and find variables, functions, etc. You can even potentially build from an IDE. A free IDE that many developers use is VSCode. Give it a try!
Create a Fork
When you’re ready to make changes to the code, it’s time to create a fork. As I mentioned, a fork is a full, private copy of a repository. This is your sandbox to make changes and try things out. In general, the normal flow of changes on GitHub is to make changes on your fork, test, then create a pull request from your fork to the main repository (i.e. push your changes to GitHub for review). Some projects allow you to create pull requests from a branch on the main repository, but this is not standard.
To create a fork, hit the Fork button on the project page on GitHub (circled in green in Figure 9).
Figure 9 - Create a Fork
Make yourself the owner, and I’d recommend leaving the repository name as-is for easy identification later. When you’re ready, hit Create Fork. Note that your fork will only exist in GitHub until you clone it (see next section).
Clone Your Fork
Now that you have a fork in GitHub, it’s time to clone your fork (i.e. pull the code down to your local computer). Navigate to your fork on GitHub. You can either do this by looking at Repositories under your account, or browse to https://github.com/{YOUR-USERNAME}/{YOUR-FORK-NAME}
Substitute in your GitHub username and fork name, of course. Then, on your fork project page under the Code button (see Figure 8), select HTTPS or SSH and copy the syntax into your terminal window for the ‘git clone’ command. For example, for APIClarity, the HTTPS command is:
git clone https://github.com/{YOUR-USERNAME}/apiclarity.git
This will pull down the code from your fork onto your local machine. If you’re using HTTPS to clone the repo, you’ll need to provide your username and the personal access token you created earlier.
Refer to my suggestion about using an IDE in the “Clone the Repository” section above. It makes a world of difference when coding.
Basic Workflow
I’ll summarize the basic workflow for making changes to a project here and provide more detail below for each step.
- Create a branch
- Make changes
- Test locally
- Create a commit
- Create a pull request in GitHub
- Incorporate feedback into changes
- Test locally
- Update pull request in GitHub
- Merge pull request when approved
- Bask in the glory of having contributed to an open source project!
Create a Branch
In order to organize your code changes, it’s time to create a branch to house them. This makes it easier to create a pull request later.
A quick note on terminology – it's 2023, and there’s a big push to use inclusive language. Historically, the main branch for a repository has been called the “master” branch, but projects are moving towards calling it the “main” branch. Not all projects are there yet, but this is definitely a change for the better.
In your terminal window, navigate to the source code for your fork (created and cloned above). Run the following command to see which branch you’re on:
git status
To see what the latest commit at the head of the current branch is, run this command:
git log
The latest commit is listed at the top.
From the “main” (or “master”) branch, create a new branch:
git checkout –b {BRANCH-NAME}
When you create a branch, it will be at the same commit (i.e. head) as the branch it came from. So, if you started on the main branch of your fork and created a new branch, both the main branch and your new branch will be at the same commit. Note that your fork will not be updated with new commits that are merged into the main repo on GitHub. To get the latest changes, you’ll need to rebase (more on that later).
A suggestion – there's some tooling in git-extras that’s a cool way to view your branches and which commits they’re on. With git-extras installed, run the following:
git show-tree
Note that any changes you make on your cloned fork are only on your local machine until you push them up to the fork.
Make Changes
Now that you have a branch, you can start to make changes. If you’re using an editor to modify files, the changes won’t show up until you save the file. If you’re using an IDE, the changes show up immediately.
To see the changes you’ve made, run this command:
git status
Initially, your changes will show up under the heading “Changes not staged for commit.” This just means that you haven’t added the changes to a commit yet, so if you were to try to create a pull request, they wouldn’t be included. You don’t have to worry about that until you’re ready to create a commit and a pull request.
You can use this command to get a diff of your changes:
git diff
Test Locally
Make changes, build, test and keep going until your change is working the way you expect it to, and you’ve accounted for any error handling and unit tests.
Create a Commit
Once everything looks good, you can add your changes into a commit by first doing this for each file:
git add {FILENAME}
You can add the ‘- A’ option to the above command to add all changes, but this can get messy if there are things you don’t want to include. I prefer to add the files individually.
Once you’ve added your files, when you run git status again, they’ll show up under the heading “Changes to be committed.”
Use this command to create a commit:
git commit
Add a brief description of your change, and an issue number if applicable.
When you run git log again, you’ll see your commit at the top (i.e. head).
Your changes won’t show up with git status once you’ve committed them to the branch. You can use git show to see the changes once committed.
Note that your commit is still only on your local machine at this point.
Create a Pull Request
When you’re ready for a code review from the community, push your changes up to your fork on GitHub and create a pull request.
Use this command to push a commit to your fork on GitHub for the first time:
git push –u origin {BRANCH-NAME}
The output from this command will give you the GitHub URL for the changes. Browse to that URL, and you’ll see the “Open a pull request” UI. Look at the top and make sure the pull request is listing the head repository as your private fork, the compare branch as your new branch on the fork, the base repository as the project’s repo, and the base branch as main or master. You’ll see your commit message listed, and a diff of your changes below. If everything looks good, click on Create pull request.
Your pull request will now be listed under the project’s pull requests, and it’s open for feedback from the community.
Incorporate Feedback
Any feedback from the community will be listed on the pull request. Remember that if you’ve gotten feedback, someone took the time to consider your changes, so the suggestions deserve consideration.
Make any changes on your local branch and test them thoroughly.
When the changes are ready, create a new commit for them on your branch.
Update Pull Request
Once your revised changes are ready for review, update your pull request on GitHub.
To do this, run this command:
git push origin {BRANCH-NAME}
Note that you don’t need the ‘-u’ option here, as the branch already exists on your fork in GitHub.
Now when you look at your pull request, you’ll see the new changes added.
Merge Your Pull Request
Once your changes are approved, you can merge your pull request into the main branch of the project. If you go to the project page on GitHub, you’ll see your new commit at the top. Congratulations, you’re now part of the open source community!
Advanced Topics
There are other advanced topics that you’ll eventually need to master. I’ll leave links here for each so you can reference them when needed:
- git remote
- git fetch
- git rebase/merge
- git pull
- git cherry-pick
- git commit --amend
- git reset
- git stash
Conclusion
Hopefully you’ve found this blog useful to understand what open source software is, why you might want to work on it, and how to get involved. Give it a try and see where it takes you!
Anne McCormick is a cloud architect and open-source advocate in Cisco’s Emerging Technology & Incubation organization.
Top comments (1)
Awesome post on open source software!