Getting unstuck

This week's theme for Outreachy blogs is "Everybody struggles". And that is true when applied to software development and even, to narrow it down a bit, to contributing to open source projects without much experience of doing so.

Many popular projects on GitHub have vast, sprawling codebases that took years to get that large and complicated with the help of hundreds of contributors. There are so many pitfalls before that first contribution can be made:

1) You can't even set up the project locally (this can happen for a myriad of reasons: no. 1 is outdated documentation with important steps missing).

2) You have set it up and made a change but cannot see it reflected anywhere (some code, somewhere, probably needs to be compiled, or else a debug/development mode needs to be enabled).

3) You have written some code and committed it, opened a pull request but out of the 186 (only slightly exaggerating there) checks run over your PR automatically a dozen or so fail and you need to dig through the failing jobs to find out if it's anything to do with your changes.

Sometimes I wonder if that relatively small change I wanted to contribute was worth the extra hours hunting down all the failing tests and fixing any code style issues, but those hours add valuable experience which means that for the next PR I will know where to look and how to fix everything I've encountered before, and I will spend far less time doing so.

There is additional value to the project you can add by going over your stumbling blocks and making sure the path for others (including the future you who may come back to this project after a break doing something else) is clear.

Documentation outdated? Open an issue or a PR with suggestions on how to bring it up to date. Code style checks failing? Make sure your IDE formats the code automatically according to the project's requirements and add this to the project documentation so others don't spend valuable time adding fix-up commits and waiting for the checks to run again.

So how do you go from being stuck and struggling with the basics to setting up everything perfectly and having everything run so well that you actually forgot you ever had any problems?

The number one thing is you search for solutions online. That means asking Google for help. I already thought I had ninja googling skills but they have been elevated to rock star level over the past few months.

Don't forget to search through the GitHub issues and discussions as well - often a comment from another contributor who had the same problem some months ago and was kind enough to post a solution saves the day.

Number two is you ask others for help. This isn't always easy or practical and there is an unsaid expectation that you will work out at least some things yourself. Many contributors are patient and kind with beginners' questions about their project but the pointers they provide are best treated as just that - a nudge in the right direction - rather than a complete step-by-step solution to whatever issue you are experiencing.

If the answer you got actually solves all problems - great! If not, try the suggested steps, see how far they take you, search online some more and only then go back and ask an informed question such as "I've tried A (what you suggested), as well as B and C (what Google came up with) - these solutions seem to work for others but don't get me anywhere. Any tips?" rather than "I've done what you suggested but nothing works. What do I do next?".

The important thing is that you have tried solving this on your own, it doesn't matter that you didn't initially succeed. And bit by bit your (ninja? rock star? any other dubious term I could use? ah yes, unicorn!)... Your unicorn googling skills, the knowledge of the codebase and the tech stack you're working with accumulate and before long you will look back at this time and wonder what the fuss was about and how you could possibly spend hours on what now takes mere minutes.

Here's what took me hours to debug recently: an innocent-looking TypeScript error that prevented my code from compiling. I googled it and the solution seemed simple. I applied it and the code blew up: a small error turned into a pageful of cascading errors that I didn't really understand. So I googled some more, and applied a different solution. No luck!

But the issue still seemed so trivial that I didn't reach out for help. I was just on the verge of fixing it, barely 30 seconds away from seeing the squiggly red lines disappear from underneath the offending line of code. Reader, I was 30 seconds away from fixing it for several hours that flew by as I tried absolutely everything I could think of.

I fixed it in the end, and a couple of days later, when I got stuck on a strangely familiar but a different TypeScript error I was able to make TypeScript happy within a few minutes. If that hadn't been the case, I would have asked one of my mentors to help. This would mean I would have to set this task aside and work on something else due to time zone differences, but it would still be a better outcome (aka something actually accomplished) than fruitlessly chasing my own tail for hours.

I'm now more aware of the gaps in my knowledge and able to assess how well the task is defined and if I should be asking any questions upfront about how to proceed with it. The secret to getting unstuck is... convincing yourself that you're not a superhero and should accept help from other people.