How do I understand an open-source project?
When I first look at an open-source project, I usually start with a prompt like this:
“Tell me about this project. Focus on its business logic, the problems it solves, and the user workflow. Explain it simply enough for a junior computer science student to understand.”
I believe understanding code written by other people is quite challenging, but also interesting.
When I first learned programming, I was taught that the main function is the entry point of a program. Technically, that is true. However, I don’t think it is always the best entry point for a human trying to understand a large software project.
Instead, I try to focus on a few questions first:
- Why was this project created?
- What problem does it solve?
- How do users interact with it?
- How does the system handle those workflows internally?
After getting a high-level understanding, I download the repository and open it in my IDE, usually VS Code.
Then I use another prompt:
“To understand what you mentioned, where should I start in the codebase? Describe the flow step by step for each use case.”
This helps me follow the actual workflow at the code level.
For me, this is also the starting point for understanding how security works in practice. However, I don’t immediately investigate security issues at this stage. I first try to understand the core workflows through as many use cases as possible.
Once I understand how the application is supposed to work, it becomes much easier to think about how it could fail, be misused, or become vulnerable.
Then, why do I do this?
I have learned many concepts, architectures, and ideas from open-source projects, including software engineering, cybersecurity, infrastructure, and many other areas.
Contributing taught me even more than reading did. Every issue I reported and every change I proposed showed me something I would not have learned on my own. Now I want other people to learn alongside me, and that is a big part of why I keep contributing: what I find, fix, and write up becomes something the next person can learn from.
I want to share what I have learned and contribute my own experience in return.
Open source has helped me pursue my interests and passion, so I believe I should also give something back—whether that means providing feedback, fixing problems, improving documentation, or contributing code.
There is another reason as well.
Through open-source contributions, I can improve both my collaboration skills and my technical knowledge.
Every project has maintainers who manage the project and communicate its direction to contributors. Different teams have different directions, different cultures, and different ways of working.
This means that contributing to open source is not only about learning code.
I can also learn how maintainers communicate, how teams make decisions, how contributors collaborate, and how different engineering cultures work in practice.
At the same time, every project uses different technologies, architectures, and development practices. Whenever I discover a new open-source project, I look forward to learning something new—not only about engineering, but also about the people behind the project.
Coming from a consulting background, one of my biggest pain points has been the gap between understanding technology conceptually and actually building and operating software.
Compared with engineers who run their own services, I sometimes felt that I lacked both the engineering mindset and hands-on experience.
I believe contributing to open source is one way to overcome that gap.
By reading real-world code, understanding how systems are designed, communicating with maintainers, adapting to different team cultures, and making actual contributions, I can gradually become a better engineer.
And along the way, I hope what I share helps others learn a little faster too.