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 () 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.
- 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).
- 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. :)
- Get comfy and watch The Myth of the Genius Programmer.
Find a simple issue to start with
- 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.
- 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.)
- Fork the repository.
- Forking will create your own writable copy of the repository within your GitHub space.
- 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.
- Or copy "Clone URL" and paste it in Visual Studio's Team Explorer on the "Manage Connections" tab.
- Now there are three copies of the repository.
- Open the project in Visual Studio.
- Create a new branch (this helps to keep your changes isolated).
- Go to "Team Explorer -> Branches" and right-click the master branch.
- Select "New Local branch from..." and name it accordingly.
- Code your changes.
- Once you're finished with implementation, make sure your code complies with contribution guidelines.
- 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.
- To push your changes further into your GitHub repository, go to "Team Explorer -> Sync" and click:
- Publish - if you are doing it for the first time (this will copy your new local branch to GitHub).
- Push - if you are doing it for the second and all subsequent time(s).
- Open your browser and go to your feature branch. (e.g.: https://github.com/<username>/KInspector/tree/<branchname>)
- Click the "Compare & pull request" button.
- Provide a meaningful description of your changes and submit a pull request.
- Wait until we review the code (we may merge it directly or suggest some additional changes).
The whole flow looks like this:
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 button. You can also leave your comments in issues.
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!