TL;DR;
That writing aims to be a bit motivational and explanatory, of why and how you should start contributing to Open Source and in particular how I do set up my development environment for Harbor!
Why?
Ok Ok, I know there are many articles out there discussing "exactly" the same topic, but I want to share my personal experience in Open Source and I will use Project Harbor! as example.
Contributing to Open Source can be daunting indeed, but also fun, educational, eye-opening, and most of all allows you to communicate with folks all around the flat Earth which I find to be most fascinating of all. That mixture of personal, technical, and sprinkled with cultural differences make difference to Open Source as one of the most satisfying and fulfilling activities of my working day!
What are Contributions?
Whenever someone mentions contributions to Open Source self-doubt in many folks arises on the surface, including myself:
"Am I good enough?"
"If I do it and my code is not on level how embarrassed that will make me feel?"
"Are the other hard-core 🤘 maintainers going to make fun of me and my PRs?"
....that list can continue on and on.
The harsh truth is...all that can happen indeed, but the other side of the coin is:
YOU HAVE TO TRY!
....and when you have your first PR/MR merged you will be over the roof.
The other thing that comes to mind when we talk about contributions is "code"... BUT not everything is code..right?!?! Contributions can be:
Answering questions on Slack/Discord or whatever else platform the project uses to address user questions or dev questions.
Helping others in the Github/GitLab Issues
When new(and old) documentation is released, test it out, fix technical and grammatical issues with it
A lot of times the project website needs update or needs something to be reworked, reorganized or just make it more readable or pretty
Help with community meetings
...
That list can grow over time but I hope I made the point, not all contributions need to be CODE! But CODE is good so...
Work on what?
The desire to contribute can come from different places.
Personal - you want to gain experience in a particular technology or language. Or you want to get to know the folks within the project. You really like the project and have some great ideas on how to improve it and make it better so you open the revolutionary feature request(proposal).
Corporate - your employer is either interested in or using a particular project. Great setup is if your employer is happy to sponsor you, in other words, happy if you spend some effort in your working hours to contribute to the project either the company is building a service based on the project or it's used internally, and that gives them a level of confidence in the project direction and management.
Regardless of the reason behind your motivation to contribute it's always a good starting point to check the "first-good-issue" labeled issues.
https://goodfirstissue.dev/ - is a great starting point if you are not sure what and where to look!
How to Contribute to Harbor
Project Harbor is structured in a few repositories under the goharbor organization in GitHub. The main repositories are:
harbor - hosts the main source code
community - hosts the community structure and feature proposals
website - hosts the website and documentation
If you are completely new to a project that you like and want to contribute to in most OSS projects a good starting point would be:
Join the project's Slack/Discord and get an idea of how active these channels are, what kind of issues people discuss and what is the overall energy and vibe in the project space
Start joining Community meetings and Office hours
Join a mailing list or Google group - so you won't miss new release updates or updated community meeting invite
These are the starting points if you want to be part of the team behind the project.
The next step would be to get acquainted with the project structure and main roles:
Go over the GOVERNANCE.md to get an idea who decisions are made and how the project community works on a high level
Check MAINTAINERS.md - understand who is who in the project and potentially who is the right person for the area of the project that you want to contribute on.
And finally and maybe most informational is CONTRIBUTING.md to actually see how you can set up your environment what you need to have installed and how you can start developing your fascinating new feature.
Once you have all that in place you can start working and create your first PR within the project.
Setup for Contributing to Harbor
That part will be my showing my setup for the Harbor dev environment based on my reading of CONTRIBUTING.md.
First of all, I'm a happy Mac M1 user which means standard x68 development work needs some hacking around to be more close to the native dev.
Either by running everything locally with x64 FLAGS which can be daunting or setting up a local VM either by Fusion or Parallels.
I'm my case I'm running a Virtual Machine in Google Cloud.
CentOS 7 x86_64 - yeah I'm a CentOS head :)
e2-standard-4 - running in europe-west1-b which is closer to home :)(Sofia, Bulgaria)
Additional disk space like 200 GB disk where I can check out the repository and store docker images
To share some money I have scheduled the VM to automatically start at 10:00 and stop at 17:30
Of course, you need to access the VM so a static IP is needed, so I can always access it by ssh. Example of my ~/.ssh/config
Host harbor-dev Hostname XX.XX.XX.XX User user IdentityFile ~/.ssh/id_rsaWhere XX.XX.XX.XX is the IP given by your cloud provider
You will need an public ssh-key attached to the VM and a private one on my machine, in my case - ~/.ssh/id_rsa.
Then you just ssh to the machine:
$ ssh harbor-devEasy right? :)
Setting up the dev env
Once you are in you have to set up the machine so you can do some work, in that case, I have to install a few components to make that possible here is a simple list of the tools you may need in almost all open source project:
git
docker-compose
make
golang
Setting up the repository
As always first you need to fork the harbor pository. Get the forked repository link from your GitHub account and clone it locally:
git clone https://github.com/OrlinVasilev/harbor.git
cd harbor
# The get the link to the original repository
# and add it s `upstream` remote:
git remote add upstream https://github.com/goharbor/harbor.git
#List all remotes
git remote -v
You should see some output like:
[ovasilev@harbor-dev harbor]$ git remote -v
origin https://github.com/OrlinVasilev/harbor.git (fetch)
origin https://github.com/OrlinVasilev/harbor.git (push)
upstream https://github.com/goharbor/harbor.git (fetch)
upstream https://github.com/goharbor/harbor.git (push)
I always do a bunch of shell aliases and in this case, is to sync the 'upstream/main' with my fork, with that, I can easily keep my local copy in sync!
alias gs="git fetch upstream && git merge upstream/main \
&& git rebase upstream/main"
Setup VSCode for remote dev on Harbor
I'm using a VSCode extension called SSH Remove
with Shift+CMD+P open the VSCode prompt and type ssh-remote..
Then scroll to "Add new SSH Host" and follow the steps to configure the host to connect(our VM in the GCP in my case).
Once configured Shit+CMD+P again .. ssh-remote choose your added VM and connect :)
Then open your home directory.
Building Harbor
To complete the setup and be able to build Harbor you need few more steps from here compile guide:
cp make/harbor.yml.tmpl make/harbor.yml
# Make necessary changes like FQDN,
# and SSL certs(more on this in the next article)
# as described in the documentation
# Compiling it with 'time' will give you an idea of how much time it took.
# and if you want to test again be prepared for the wait :)
time make install COMPILETAG=compile_golangimage
If you are lucky today after a few minutes in my case ~20 you should have up and running self-compiled and started Harbor.
In the next few articles, you will find guides on how to setup Harbor with Let's Encrypt and how to write and and test your first PR.
Congratulations! :)