pncnmnp / oss-guide

A handbook to help people getting started with open source contributions

OSS-Guide

Motivation

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?

What does this website encompass?

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 -

  • Fellow developers to share their experiences navigating any codebase, and
  • Maintainers to share ways in which new contributors can begin exploring their open-source repos

• 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.

Technology

The playground backend is crafted using Flask. The entire frontend uses Docusaurus - version 2 and React.

Add a story

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 to the general guide

To contribute -

• First fork and clone the OSS Guide repository.
• Then navigate to OSS-Guide/guide/general.md for general guide or OSS-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.

To contribute a feature/fix

Please file an issue here.