Jumping into a large open-source project with no prior experience navigating such a codebase can certainly seem daunting. MLH Fellowship's Open-source track gives a platform for such budding contributors to learn and hone these skills. However, oftentimes, the beginning weeks can seem challenging and the challenge usually lies in this one question - How to understand the large codebase of an open-source project?
This handbook helps fellows out with the same. We have divided this project into 3 sections -
-
General Guide and Exploring - This contains general information about how one can proceed to contribute to open-source. We have carefully crafted this and it presently contains the following topics -
- Choosing a Project - How to go about selecting a project to contribute to?
- Getting Started with a Repository - How to make those baby steps? Contains sub-topics like -
- start using it first
- check out the earliest commits
- read/write test cases, specifications, and build from source.
- wield tools such as call-graphs and UML digarams
- a handy
git log
trick - searching a large codebase using Github's build-in search, grep, or ctags
- Discovering issues - How to explore a repository's issues
- Planning - How should you plan your fix/feature? Contains sub-topics like -
- Use the issue description to its fullest
- Don’t try to go through the whole codebase
- Figure out how your part fits in
- Reproduce the issue
- Structured Theorizing
- Coding and Guidance - What to keep in mind while coding? Contains sub-topics like -
- Feedback from mentors and maintainers
- Debugging, Logging, and Profilers
- Claim an issue
- Exploring - This contains a list of interesting links regarding these very topics and also contains a special thanks section.
-
Stories - As mentioned in the Welcome guide of stories section, this space was formulated to enable -
-
Playground - Here, users can play around with code-snippets and generate UML diagrams, call graphs on the fly! We are planning to add a live debugging, profiler, and git playground.
The playground backend is crafted using Flask
. The entire frontend uses Docusaurus - version 2
and React
.
To add a story -
- First fork and clone the OSS Guide repository.
- Then navigate to
OSS-Guide/guide/blog/
and create a markdown file of the format -YYYY-MM-DD-my-blog-post-title.md
. - Insert your story inside the
.md
file, commit, and send a Pull Request to the main branch of our repository.
To contribute -
- First fork and clone the OSS Guide repository.
- Then navigate to
OSS-Guide/guide/general.md
for general guide orOSS-Guide/guide/resources.md
for the exploring section. - Contribute your changes inside the above files, commit, and send a Pull Request to the main branch of our repository.
Please file an issue here.