What I Learned From Hacktoberfest 🍺
If you are unaware, there is a Hacktoberfest event going on right now. The rules are simple :
- If you have an open-source project and need some help — just create some Issues in Github and label them with “Hacktoberfest”
- If you’d like to contribute to some open-source projects — just sign up on the Hacktoberfest website, pick a project you are interested in, and help them squash some juicy juicy bugs 🐞 !
Oh did I mention there are FREE t-shirts ? Yep, you get a sweet Hacktoberfest shirt if you contribute 4 times. Easy, right? I couldn’t wait to add this shirt to my “T-Shirts-That-I-Got-For-Free-From-All-Kinds-Of-Events-But-Too-Self-Conscious-To-Wear-In-Public” collection, so I jumped on my iTerm and VS Code as soon as I got home from work last night.
So after 4 full hours of hard work — I have successfully created…2 pull requests. Just two more to get my shirt, but I decided that’s enough Github issue window-shopping in one day (or maybe one week).
I’ll admit that I’m not a hacking pro like Elliot Alderson, but this is way below my expectation. What went wrong? It turns out that, at least for me, it’s actually really hard to find something I can actually work on.
If you are a project owner, and want some help. Here’s what I learned:
- When you create an issue, please do write a description. When you write a description, please be as specific as possible.
If you browse Hacktoberfest issues now — it’s not hard to find tons of issues with no description (and often with a very vague title). I’m sorry, I know Webpack and Babel work like black magic but we can’t read your minds. I used to be a scrum master who works with product managers closely — I learned how important it is to have well written stories. Maybe your open-source project doesn’t have to have Stephen King’s story writing, but at least you should let your contributors know what you need to be done.
Exhibit A: Title: “Add Docs”, Description: `null`. I’ve seen this kind of issues on several pages. Writing docs might be one of the easiest ways to get involved in the exciting open source world. But are you being too lazy here, repo owner? Are you expecting someone would pop out of nowhere and document your project like History channel?
Here’s what I’d do (but didn’t do)
$ echo TODO >> Docs.md
$ git add .
$ git commit -m "Paves the way for more docs. You are welcome."
$ git push
Well, there are some very good examples of proper “issue writing” in this Hacktoberfest though. One of my two pull request fixes an issue that is well documented and has clear instructions. Even though I don’t agree with some of the design/style choices that the owner made, but it is their project and I respect that. Being able to complete something per spec is actually very enjoyable for me. Hopefully it’ll be the same for the owner too when my pull request is merged. 🍻
2. Have a clearly written CONTRIBUTING file that lists all the top level dependencies, and includes a step-by-step guide to setting up a development environment for your project. Oh, and make sure you test it in from a clean state.
I don’t remember how much time I have spent on forking and cloning but ended up
rm -rf everything because I couldn’t figure out how to spin it up. Maybe it is because I’m not smart enough. But you should spend some time to make sure you have a guide and your guide makes sense.
You could start by listing your tech stack. For example, what languages/packages are needed for your project — and which versions? Node 7? Rails 5? Or maybe your app requires Postgres 10 instead of 9.5. Not all of them can be defined in your regular
Gemfile . For certain packages, like
imagemagick , know it might be tricky to set it up on certain systems.
You should learn Docker.
It is really not that hard even if you don’t know much about DevOps. To be honest, I never really cared about learning Docker, until my team has to on-board a new developer. We work on a big project that has been under active development for quite a few years, uses a lot of different technologies, and has a very, very long dependency list. I spent a whole Friday trying to get the dev environment up and running on a new machine, but all I got was all kinds of errors and unexpected dependency problems. All the warning messages I ignored over the years have finally had enough of me and turned into big, red, catastrophic errors.
It was a very frustrating experience for me. And I was experiencing it again when trying to help out some of the Hacktoberfest projects.
After I went home on that Friday. I sat in from of my computer and watched hours and hours of Docker tutorials. I spent the whole weekend fixing all the errors while trying to set up Dockerfiles for our project.
Then on Monday morning. I went to our new dev, helped him install docker, and
docker-compose up . Magic. He’s ready to go.
I wish I could do that with all open-source projects. I wish I don’t have to maintain 5 different version of Ruby, and put two hundred
node_modules directory on my machine.
3. List your issues’ dependencies if there are any.
This one is actually pretty straight forward. If fixing one of your issue depends on another issue that needs to be fixed first. I saw this a couple of times in some projects that are asking for help completing some features. Then I discovered many of those feature requests depends on other features to be done first.
Unfortunately Github currently doesn’t automatically show which issue is being blocked by others. You could mention this in the description, tag the issues that are blocking the one you are writing with #IssueNumber.
4. Write Your Own (Unit) Tests
I understand you are so focused on your proud open-source project. You pulled so many late nights to ship all those shiny features. So you didn’t write any unit tests at all.
If you are an experienced developer, writing silly unit test might be below you. You know your function is going to work like magic so why bother testing if
true truly equals to
true ? So you created five Hacktoberfest issues: “Please add unit tests for AwesomeModule.js”, “Please complete my unit tests”, or even “please improve my code coverage to 300%”.
Maybe it is just me. But I don’t believe writing unit tests can be separated from writing actual code. Your code might be awesome and all, but it doesn’t mean it can be tested properly. Maybe you know exactly what’s going on with your 20 nested if statements, but it doesn’t mean someone else should accept their fate and write tests for every possible combination for you.
If you are a really experienced developer. You don’t necessarily write tests before your code. But you always write your own unit tests. Your tests not only verify your code, but also help you write better code. You might end up refactoring a big chunk of your app to make it easier to be tested. And that’s a good thing.
Remember “rubber duck debugging”? My rubber duck has been retired for a long time. He still sits on my desk, watching over his successor — thousands of unit tests that are being executed every time I
If you still think writing unit tests are too easy. Well, I challenge you to write some proper tests for the famous Fast InvSqrt(). Without reading any explanation or anything:
float Q_rsqrt( float number )
float x2, y;
const float threehalfs = 1.5F;
x2 = number * 0.5F;
y = number;
i = * ( long * ) &y; // evil floating point bit level hacking
i = 0x5f3759df - ( i >> 1 ); // what the fuck?
y = * ( float * ) &i;
y = y * ( threehalfs - ( x2 * y * y ) ); // 1st iteration
// y = y * ( threehalfs - ( x2 * y * y ) ); // 2nd iteration, this can be removed
Maybe it’s enough ranting for me today. :)
I absolutely love Hacktoberfest and I want to say “Thank you” to everyone who is involved in making this happen. I’ve been working in software as a professional for 8 years but I’m still too shy to make any of my side projects public. You are better than me, everyone who is making their projects publicly available and boldly labeling them
After this event, maybe I will keep going, even if there are no free shirts. Now, it’s time for me to go back to issue browsing and actually squash some bugs.