Abstract
This post will cover a few steps to follow when first onboarding and working with a new codebase. The article will also share some challenges that may arise, and an example of applying the 'Understand-Mindmap-Code!' approach. This article is beginner friendly, however, it is assumed that the reader has understanding of how to get a development environment setup based on the project they're contributing to. If further knowledge on the aforementioned is needed, please view this resource.
Step 1: Understand the Issue
Whether you're looking to sign up for an issue, or are currently working on one, but feel stuck, overwhelmed, and don't know where to start - take a pause. Try to focus on fully understanding what the task is asking of you. This will help isolate where in the codebase you need to start. Taking the time to clear assumptions, understand the requirements and expectations of the task will help avoid confusion and address knowledge gaps.
If there's verbiage or technical concepts you're not familiar with, start by gaining an understanding of the tools or tech stack that may be needed to complete the task. You can do this by Google searching the documentation. It is important to filter out technical concepts that you don't necessarily need to be an expert in to make progress. After you've spent some time digesting the requirements and communicating any assumptions, you can move on to exploring the codebase.
To summarize, Step 1 consists of the following micro-steps:
- Understand what the issue is asking you to do
- Clear any assumptions (you can utilize GitHub to communicate with maintainers or fellow open source contributors)
- Determine what technologies / tools you will need to complete the task
Step 2: 'Mindmapping' the Codebase
The next step is to isolate where in the codebase you need to make changes. This may require understanding code / functionality in other areas of the codebase, and this is where 'Mindampping' comes in handy. This can be achieved by writing notes, logging to the console, making a diagram, or any way for you to visualize and connect the dots on how the functionality coexists. By observing the behaviour of the codebase's ecosystem, you can create a mental map for you to follow.
Step 3: Code!
Now that you understand the issue and know where in the codebase you need to work, you can start coding! You may want to start with some pseudocode / MVP and iterate on that. By having a firm grasp of the functional requirements and a 'Mindmap' to guide you, you should be able to abstract a larger task into smaller micro tasks. This can make completing the issue less overwhelming.
Applying the 'Understand-Mindmap-Code!' Approach
I applied this approach myself to an open source project called Classroom; A self-hosted solution to help teachers plan and manage classroom-based learning, on top of freeCodeCamp's learning platform. The issue I was working on involved refactoring how the API response was received and rendered in a dashboard UI.
I began by understanding what the task was asking of me. I cleared any assumptions with one of the maintainers of the project, and isolated what technologies / tools I would need to familiarize or refamiliarize myself with. Through this process I determined it was necessary to have a solid understanding of Next.js, React, Node and API handling.
I then moved on to 'Mindmapping' by isolating where in the codebase was relevant for me to complete my task. Through this I was able to improve the documentation of the project which fellow open source contributors would be able to utilize in the future. The contribution can be viewed here.
Then I was finally able to write the code needed to complete the task, allowing the open source project to move forward. The contribution can be viewed here.
Summary
In conclusion, onboarding and working with a new codebase can be a daunting task, but it doesn't have to be overwhelming. By following the 'Understand-Mindmap-Code!' approach outlined in this blog post, you can tackle the challenge with confidence and efficiency.
Remember, taking the time to fully understand the task, communicating with project maintainers, and familiarizing yourself with the necessary technologies are crucial initial steps. Creating a 'Mindmap' of the codebase will serve as your guide, helping you navigate and comprehend the intricate interactions between different components.
With a clear roadmap in mind, you can dive into coding, breaking down the task into manageable chunks. This iterative process allows you to progress steadily and tackle any obstacles that may arise.
As demonstrated by the example of my contribution to the Classroom project, following this approach can lead to successful code refactoring and project advancement.
So, the next time you find yourself facing a new codebase, don't let it intimidate you, and you'll be well-equipped to make meaningful contributions and grow as a developer.
Happy coding!
Top comments (0)