Hello Human 👋🏻

So do you want to contribute to open source? Awesome.

Does it sounds overwhelming? That's also normal.

Hacktoberfest is designed to lower somewhat the friction, but it can't possibly remove it. That's why I thought it could be useful to share some guidance on how to make simpler but more meaningful contributions.

Before we start

Keep in mind that what I propose here is my personal guidance. Some smart people will disagre. That's why they end by an asterisk*.

Actually my guidance are mostly questions in disguise. The goal is to nudge you to ask yourself better questions. If you find my solutions helpful, I'm glad. If you do the job of asking yourself better questions and come to a different solution, I am also glad. And I congratulate you.

So let's started by not speaking about programming.

Don't focus only on the technical aspects

There are plenty of good articles here on all sorts of topics like #github #hacktoberfest #typescript #beginners #html #css #react #vue #kotlin #swift #golang

The technical stuff is important but in my experience, it is not the whole picture. There is another aspect that I talked about in one of my weirdest and personal favorite article: Contributing to open-source is like dancing Tango

As I said in my post, when you take dancing lessons, there is a strange moment when the teacher say something like this:

And now, ladies and gentlemen,
please choose a partner among all those unknown people
and start dancing together very closely. 🕺🏻💃

This is inherently awkward. Some people try to work around it by dancing only with the same dancer. But there is no way around it. You have to learn to do that well.

The secret is to develop empathy.

So how do you develop empathy?

Well it took me a lot of time to work on my empathy skills until I discover a small secret:

Dance both sides of the game
Chances are that when you started a social dance like tango, you learned to be a leader if you were a man, and a follower if you were a woman. There is something magical about experiencing both perspectives that will change you. By feeling both side of the same game, you inevitably gain a much deeper understanding of the dance. It becomes also much easier to empathize with your fellow dancer.

The analogy is here obvious: you cannot really get open-source if you have only been a maintainer or only a contributor.

So that's a long term plan, but in the short term you really should focus on creating a human connection with the maintainers.

Which brings me to my next point.

Don't send a Pull Request*

What? Isn't the whole point of hacktoberfest that you have to submit 4 (?) pull requests?

Well yes and no. The four PRs are a gamification trick to nudge you to learn how to contribute to Open Source. The real goal then is to become better at contributing to open source.

Now if you talk with open source maintainers, they may tell you they feel bad when a contributor comes with great intentions, and start hacking for a long time alone in his basement until the moment where the PR is finally perfect and ready!

Unfortunately it's not so simple:

• the maintainer may be overbusy with life right now, like she just got her first child
• the maintainer doesn't actually maintain the repository, because we all have more old projects than time to work on them
• the maintainer may have fixed since months the problem spent energy fixing. It was just in another branch
• the maintianer may see that there is a right idea behind your PR, but unknown to you there was a 10 times simpler solution to address it
• and just git being git and getting in the way

That's why contributing to open source can feel oh-so-frustrating sometimes. For everyone involved.

Fortunately there is an easy solution

Never start with a PR on a unknown project from unknown people.
Start by creating an issue of you explain WHY you think something deserves to be improved, and let the maintainers tell you whether that makes sense for him, and if yes guide you on HOW to do it the easy way.

Please read this again, this is really the key to make your contribution effort both simpler and more meaningful.

I can share my simplest and more meaningful contribution as an example:

Here I noticed a very small thing that could be an actually meaningful improvment. I could have sent a pull request. But I didn't.

Instead I applied the principle Start With Why

Start With Why

I am really proud of this contribution to the incredible Homebrew project. You wil see it's simple. And that's exactly my point. It's really good that it's so simple.

All started with an issue:

Here I didn't only reaquest a feature. I also explained very clearly my motivation for wanting this feature. Namely Lazyness, one of the great virtues.

What followed was just awesome. MikeMcQuaid, project leader of the Hombrew project immediatly replied

I love, admire and agree with the honest admission of laziness here. Given how little code would be required to implement this: would definitely review a PR.

Soon after some fellow smart people with vastly greater knowledge of Homebrew than me came up immediatly with multiple solutions. I am happy that I had shut up about the solution I had in mind. If would have created a completly different discussion.

Once this connection was established, I was more than ready to implement the PR myself. As it turned out, I didn't even have to because soon after Try MacCabe took care of it better than I could.

I'm on my MacBook pro right now and brew docs does exactly what I intended.

So what di we learn?

We learned that what matters is focus and communication.
Not the amount of efforts

Which brings me to my next, possibly contreversial, point.

Don't learn the git CLI*

Many smart people firmly believe that the git CLI is the basis of everything and you definitely should spend a considerable amount of time struggling with it and copy-pasting answers from Stack Overflow when you will inevitably mess up.

For your information, don't stress out if you git mess --up often. People with years of git experience still git mess --up things regularly.

I'm not saying that they are wrong, I'm saying that I focus on something else.

I focus on learning the concepts

What matters then is what helps people to learn the concepts and what hinders it. The accidental complexity of the GIT CLI is in my opinion a major obstacle to learning. I believe in making it easy to do the simple things and in helping to prevent developer mistakes.

Contrary to what you may think, it's not a debate of GUI vs terminal applications.
If you like the terminal I recommend to use GitHub CLI and/or lazygit
If you like GUI applications I reommend GitHub Desktop, or the IMHO awesome git integration in IntelliJ, WebStorm, PHPStorm, RubyMine, PyCharm, ...

All those git applications were designed with simplicity and usability in mind. They will help you focus on what matters most: learning the concepts.

Again this is my personal advice that doesn't universally apply. If you are an hardcore C programmer working in project similar to the Linux Kernel project, specificallly Bazaar style, then the git CLI is the best possible tool for that use case, because it was designed by and for them.

Now for the really important stuff.

Help Maintainers See Things Through your Beginner Eyes

"The real voyage of discovery consists, not in seeking new landscapes, but in having new eyes." -- Marcel Proust

Looking at the codebase of an open source projects that has hundreds or thousands of commits and years of existence is very intimidating.

And you probably wonder how the hell you can do a meaningful contribution?

This is a great question, thank you myself for asking it.

As it turns out when you see things from the maintainer side, there is something that is really hard for us. We know that the first impression people have from our project matters a lot. The thing is we are bad at detecting this kind of things. We are so deep in our projects, we know so many details of it that it requires a huge empathy effort to see the project through the eyes of someone who discovers it for the first time.

As it turns out, that's something where you are much better than we are.

And you won't believe how few users will have the courage to give us this kind of feedback.

So my advice would be:

• pick an open source project that you like and where you seems to be the target audience.
• give it a try like you were a new user that want to try the project out and has only a limited time to evaluate it
• opens an issue (see before), tell the maintainers that you just tried the project, that you were impressed by xxx and yyy, and on the other hand you had some naive question about some other stuff. Would it be intersted by a detailed feedback?

If you give it a try, please tell me how this turns out.

Conclusion

I never have interesting conclusions to make and today is no different. On the other hand, I have a request.

I know that I'm supposed to share my article on social media to reach the kind of people it can help. But I'm just bad at social-media. So if you liked the article and Twitter, Reddit, ... is your thing, I would really appreciate if you can do it for me.