A journey into Open Source • Step 2 - GitHub Guru

This is an entry in my code journal. I’m currently writing on the open source software world. This is mainly so that I can Google my thoughts later and even share the experience with others who plan on getting in on the OSS action. The first part was on git mastery. These entries will be constantly evolve as my knowledge grows so stay tuned. This next part is on working with GitHub.

GitHub: The intro

For those who didn’t know git wasn’t made by GitHub (believe me I’ve heard that before). It was made by Linus Torvalds, the same awesome guy that wrote the Linux kernel.

Github is actually a service that provides hosting (amongst other things) for git based projects. It’s actually where this blog is hosted!! Remember the remote repository we were talking about last time? Well Github gives you a free way to host and manage your remote repository but there’s a catch.

It’s only free when your repository is public i.e. everybody gets to see your crappy/awesome code and copy it. There’s a paid option for organizations that want to keep their repositories private. There are other popular alternatives to GitHub like Bitbucket and GitLab which give you free private repositories and many other cool features.

Under The Hood

GitHub is pretty simple to use and it has lots of good documentation on how to use it.

I’ll just focus on explaining how it is used for open source projects. Let’s say you find a good project you want to contribute to. Maybe this one (Shameless plug I know). Let’s have a look at how Github makes it easy for you to contribute to such a project.

project page

  • Code:
    This is the first tab you see when you hit the project page. It displays the contents of README.md file if it’s present. Other things you may see are general git statistics just below the project description eg. number of commit, number of branches etc.

    git stats

    It also shows you a file manager view of the source code of the project. You can navigate and view the code by clicking the links to the folders and files. Notice that the last commit message for each folder and file is displayed to the right.

    git stats

    The most important section on this tab (IMHO) is this one.

    pull request bar

    From here you can get the project link in case you want to clone it. You also get to create Pull Requests which I’ll talk about later.

  • Issue:
    GitHub gives you an issue tracker for your projects. An ‘issue’ may be a bug, a feature or even sometimes just a discussion on a particular concept used within the project.

    The issue tab usually looks like this:

    issue tab

    This is where you should look when you want to add some value to an open source project you like.

    Each issue may have a community given label that tells you what it’s about. These labels also help you filter and search quickly through issues of larger projects.

    issue item

    When an issue is opened you can discuss its resolution with people who raised the issue and with the rest of the community. This is how quite a number of people contribute to open source projects!

    issue page

    After an issue is considered resolved it is closed.

  • Pull requests:
    This I feel is the ‘killer app’ of GitHub. Every code contribution you make is put into a pull request. You aren’t allowed to directly commit changes to a project you don’t own.

    When you see an issue you want to resolve, the first thing you may have to do is fork the repository. This is more or less branching on a higher level.

    fork

    Your fork allows you clone the project, create a feature branch, write your code and then commit you changes(since you own this fork).

    After writing all that awesome code you have to create a pull request for your changes(ideally they should be small testable units of code). This allows the maintainer or the community to review your code and make a decision on whether it is ready to be merged into their project. Some communities have CI servers that run your code at this stage to make sure every thing works well.

    pull request

    This may sound intimidating but depending on the community this can actually be fun. You may get good coding advice and different ideas on how to improve your code. You can even make it a habit to review other people’s code to learn new and amazing techniques.

    N/B: most projects have rules and conventions governing how to contribute code and write issues. Please check out the Wiki tab or CONTRIBUTING.md file before writing any code or opening an issue

  • Wiki:
    This is where some projects keep their documentation and rules on how to contribute and comment. Be sure to check it out.

    wiki

    N/B: Some projects actually have their docs in the code and not in the wiki. Like Bootstrap and Wordpress Calypso

  • Pulse:
    This tab gives you more detailed git statistics on the project as well as list the number of pull request merged, number of code authors, opened and closed issues etc.

    pulse

  • Graphs:
    This gives you a more visual look into the project. Here you may see who contributes most to projects you like.

    graphs

Github has many other cool features that I haven’t covered but feel free to explore, ask questions in the comments section and get your hands dirty. Speaking of which; since this post seems really long, all handle the Getting My Hands Dirty section in another post. I’ll be setting up my environment for an actual project.

See you in the next post.

Happy Coding