Every Developer Should Be Able to Do Some PR

   —   

Don't worry, we're not going to talk about public relations, the PR in the title stands for the “pull request”, the base unit of contribution in today's open-source world. The intention of this article is to shed some light on how to start contributing in an open-source project.

As you may know, Kentico's open-source projects are hosted on GitHub, which is an online code repository system based on Git. Git is probably the most powerful version control system that is out there today, but its complexity comes hand in hand with a steep learning curve. Though GitHub tries hard to compensate for this steepness by wrapping Git in a fancy UI and making the development process straightforward, it's still not always completely clear what's going on behind the scenes. This is something that often discourages newcomers from contributing to open-source projects.

When it comes to contributions, you'll often hear people talking about "PR" or "pull requests". PR is a way of submitting your changes to an open-source project. Basically, it is a request for the maintainer of the project to pull your changes and merge them into the main codebase. When you are able to submit a pull request, you are ready to contribute. Creating a pull request has some rules and requires a certain level of knowledge. To make it easier for beginners, we put some effort into making our repositories more friendly (First Timers Friendly) and became part of Up for Grabs and First Timers Only initiatives. 

So let me take you through the process of creating your first PR.

Boost your confidence

Git is hard, GitHub is hard. So we'll need some encouragement to make the first step.

  1. Learn a little bit about the First Timers Only and Your First PR initiatives (big thanks to their authors Scott Hanselman, Charlotte Spencer and Kent C. Dodds and all propagators).
  2. Look up the first pull request of a random respected community member on http://yourfirstpr.github.io/ and laugh at it. There is a good chance that changes in your first PR will be more valuable. :)
  3. Get comfy and watch The Myth of the Genius Programmer.

Find a simple issue to start with

  1. Many repositories contain issues marked with first-timers-only and up-for-grabs labels. KInspector and AD Import Service are no exceptions. These labels are to distinguish issues that should be easy to implement and contain a detailed walk-through of the whole contribution process.
  2. You can also browse the up-for-grabs.net site, which gathers and categorizes such issues and makes them easy to find.

Submit your first PR

Assuming you already have an account on GitHub and you've chosen an issue and assigned it to yourself. (The following steps and graphics demonstrate the process on the Kentico/KInspector repository.)

  1. Fork the repository.Forking GitHub repository
    • Forking will create your own writable copy of the repository within your GitHub space.
  2. Clone your forked repository to your local machine, there are many ways to do that:
    • You can either click "Open in Visual Studio" in your repository.
    • Or click "Clone in Desktop" if you have the GitHub Desktop application installed.Cloning repository from GitHub
    • Or copy "Clone URL" and paste it in Visual Studio's Team Explorer on the "Manage Connections" tab.
      Cloning a repository from Visual Studio
  3. Now there are three copies of the repository.Upstream / origin / local repositories
  4. Open the project in Visual Studio.
  5. Create a new branch (this helps to keep your changes isolated).
    1. Go to "Team Explorer -> Branches" and right-click the master branch.
    2. Select "New Local branch from..." and name it accordingly.
  6. Code your changes.
  7. Once you're finished with implementation, make sure your code complies with contribution guidelines.
  8. Go to the "Team Explorer -> Changes" and provide a meaningful message followed by an issue identifier (e.g., "Added username validation - Fixes #10") and click the commit button. This will commit the changes to your local repository.
  9. To push your changes further into your GitHub repository, go to "Team Explorer -> Sync" and click:
    1. Publish - if you are doing it for the first time (this will copy your new local branch to GitHub).
    2. Push - if you are doing it for the second and all subsequent time(s).
  10. Open your browser and go to your feature branch. (e.g.: https://github.com/<username>/KInspector/tree/<branchname>) Pull request
  11. Click the "Compare & pull request" button.
  12. Provide a meaningful description of your changes and submit a pull request.
  13. Wait until we review the code (we may merge it directly or suggest some additional changes).

The whole flow looks like this:

Git flow

Discuss

You can always reach out to us via Gitter. Both our projects have their Gitter rooms, so just go to the repository and click the Join Gitter chat button. You can also leave your comments in issues. 

Summing up

Have you met octocat? The mascot of GitHub?

Contributing to an open-source project can be really rewarding. It's not about doing someone else's job, it's about broadening horizons, diving deep into technology you're interested in. It's a great opportunity to find out more about how things work under the hood instead of just using them blindly. 

Let your first pull request be for a Kentico repository. We are ready to help you!

Share this article on   LinkedIn

Petr Svihlik

I listen to the voice of community and act in its interest.

Comments

rhutnyk commented on

Thanks, Petr! This was really useful for me!