This content originally appeared on DEV Community 👩💻👨💻 and was authored by
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 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 disguised. 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 congratulate.
Don't focus only on the technical aspects
There are plenty of articles on how to make your first pull request, how to learn GitHub, how to learn the basics of TypeScript, Python and why not.
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 an inherently awkward moment when the teacher says something like:
And now, ladies and gentlemen,
please choose a partner among all those unknown people
and start dancing together very closely. 🕺🏻💃
It then gets slowly ok-ish, but it usually takes a lot of time.
The secret is to develop empathy.
How you do that? Good question thank you my hypocryte second me.
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 TK 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 along 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 expecially on a unknown project.
Start by creating an issue of you explain WHY you think something deserves to be improved, and let the maintainers 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
I explained very clearly not only the change I wanted to see, but also my motivation: Lazyness.
What followed was just awesome. Mike MacQuaid, 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 and lazy people came up immediatly with multiple better solutions that I had in my mind.
I was more than ready to implement the PR myself but I didn't even have to because soon after Try MacCabe took care of it better than I could.
`brew docs` as an alias for `open https://docs.brew.sh`
#13834
Provide a detailed description of the proposed feature
brew docs as a shortcut for open https://docs.brew.sh
Also udpate brew help
$ brew help
(....)
Further help:
brew commands
brew help [COMMAND]
man brew
- https://docs.brew.sh
+ brew docs
What is the motivation for the feature?
Laziness is one of the three great virtues of the programmer, as defined by Larry Wall.
Laziness is the quality that makes you go to great effort to reduce overall energy expenditure. It makes you write labor-saving programs that other people will find useful and document what you wrote so you don't have to answer so many questions about it.
How will the feature be relevant to at least 90% of Homebrew users?
Benefits for users
It makes it marginally easier to 90% of Homebrew users to access the docs at https://docs.brew.sh
And maybe find the information they need, which is nice.
Benefits for maintainers
It is marginally nicer for Homebrew maintainers that Homebrew users are empowered to find the documentation they need. They would have to repeat themselves marginally less.
Of course, many users still won't read the docs, but now maintainers can reply
This is documented in
$ brew docs, sectionCommon Issues
This kind of reply makes it marginally more likely that users read the docs next time. Yes it's just a RTFM, but I think/hope it's an empowering "Read the Friendly Manual" RTFM, not the "Read the Fucking Manual" RTFM.
Benefits for documentation writers
As someone who writes technical documentation myself, I know this is hard work and I know that I like it when more users actually use and benefit from the documentation.
What alternatives to the feature have been considered?
Bookmarking https://docs.brew.sh
But I'm too lazy to bookmark things and use browser bookmarks correctly.
I'm on my MacBook pro right now and brew docs does exactly what I intended.
As you can see, it's not the amount of efforts that count, it's how well focused they are.
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 immediatly 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 that it's my responsability as a develop to put efforts to make it easy to do the simple thing.
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 and will help you on what matters most: Learing git concepts.
Again this is my personal advice that doesn't universally apply. If you are an hardcode C programmer working in project similar to the Linux Kernel project, specificallly Bazaar style, then the git CLI is the best possible tool, because it was designed by and for them.
Now for the really important stuff.
Help Maintainers See Things Through your Beginner Mind
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 are so deep in our projects, we know so many details of it that it requires a huge effort of empathy 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.
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 don't have any conclusion but if you try some of my tips I will be definitely interesting in hearing how it went.
This content originally appeared on DEV Community 👩💻👨💻 and was authored by
| Sciencx (2022-10-01T16:46:00+00:00) Can beginners make a simple but meaningful contribution? Some unconventional advice #hacktoberfest. Retrieved from https://www.scien.cx/2022/10/01/can-beginners-make-a-simple-but-meaningful-contribution-some-unconventional-advice-hacktoberfest/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.