Open source contributions are one of the best ways to give back to the community, build your resume, and meet great people in the tech industry. However, getting started with code contribution in open source can be intimidating if you don’t know where to start. What are the baseline skills you need to pick up a good first issue? To help you get started with code contributions, here are five things you should know before getting into open source!
1. Learn how to talk the talk
Like everything else, open source requires knowledge in a few terms to navigate the space successfully. To understand and communicate with other contributors, you need to get yourself into a position where you can talk the talk.
Starting with the below ten words, learn what each word means and how it relates to open source. By understanding these terms, you’ll be able to communicate effectively with other contributors on what you’re doing, what you want to do and what you need help with.
2. Terminal (Command Line Tool) is your friend
The terminal is a tool to enter text commands directly to the computer. It’s used frequently by engineers to avoid using graphical user interfaces (GUIs) or for tasks that do not come with one.
You’re not expected to be a terminal expert, but knowing how to move up and down a directory, listing files in the current directory and finding the path of the current directory can help navigate your system to run a command in the correct place.
3. There’s no way around it — you need to learn how to Git
Git is a distributed version control system used by all open source projects to manage and keep track of changes made to the project.
To make changes to the project source, you need to utilize Git to at least clone, checkout, add, commit and push.
When you get stuck, just ask your computer for help by running git help. If you need help with a specific command like clone, run git help clone to see the description, options and example of how to run the command.
If you get stuck, don’t worry. I don’t know how many times I had to reset because I messed up my Git commands. When you do, there is no shame. We all have been there.
To continue your Git learnings further than the minimum outline here, checkout the following resources.
4. You don’t have to be a Vim expert, but you do need to know how to escape and quit
Vim is a text editor that allows you to write and edit text. The idea of a text editor is simple, yet Vim is not an easy tool to use.
Some git commands you run in your terminal may result in automatically opening Vim. When that happens, you just need to know 4 important commands.
When a Vim editor opens up, you typically need to make an edit. Since Vim starts in a state called the normal mode that gives you no ability to edit, you need to start with pressing i to initiate the insert mode.
Once insert mode has been activated, you can now edit the content of the file like a typical editor you would expect. Use your up, down, right and left arrow keys to navigate.
After completing your edits, you can’t just save and quit without going back to the normal mode. Therefore, you need to press the esc key to exit the insert mode and go back to the normal mode.
Once in the normal mode, you can now save and quit by pressing :wq + enter. If successful, the Vim editor will close automatically.
If you run into any problems during your Vim encounter, your best friend is the esc key. Always go back to the normal mode and try again. Worst case, esc + :q! to quit without saving.
5. You have to Fork the repos you don’t have access to
One thing that may not be so apparent is that open source projects are visible to all but not editable by all.
To edit the project source that’s not your own, you need to fork the repository. By forking, you are essentially copying the project into your own space. Then, you have the necessary permission to edit and push your changes to the copied version, a remote repository.
In short, if you don’t own the project, fork and then clone the forked repository.
If you directly clone the repository that’s not your own, you will not be able to push your changes due to permission issues.
Take a look at how to fork a repository in the official GitHub documentation.
Turn Tips into Action
Let’s put the five tips into action by going through how to make a pull request to an upstream project.
- Open up your browser and navigate to https://github.com/octocat/Hello-World (upstream repository).
- Press the “Fork” button (located on the top right corner) to create your copy.
- Verify that you successfully forked the project by navigating to https://github.com/<your-github-id>/Hello-World.git (remote repository).
- Open up a terminal.
- (Only required for first time git users) In the terminal window, type the following commands to set your user name and email address used for commit messages. Email provided must match the email used for your GitHub account.
- Clone the remote repository to your local machine.
- Change your current path to the “Hello-World” directory.
- Change to a new branch called “dev”.
- Open up the README file using Vim to make changes.
- Enter i to start the insert mode, then modify the existing text “Hello World!” to “Hello <Your-Name>”.
-
Enter esc to exit the insert mode.
-
Enter :wq to save and quit Vim.
- Now add your changes by running the following command in your terminal.
- Make a commit with a message describing the changes. To learn more about what a commit and a commit message should be, check out Improve Your Git Commits in Two Easy Steps.
- Push your changes to your remote repository.
- Navigate to https://github.com/<your-github-id>/Hello-World/tree/dev (dev branch of a remote repository) and verify your changes are reflected correctly in the README file.
- On the same page, click “Contribute” then the “Open pull request” button.
- Give an awesome description of what changes you made and click “Create pull request” to open a new pull request.
- Celebrate! 👏 You did it! You made your first pull request to an upstream project.
If you are not comfortable with the tools mentioned above, don’t worry. Code contributions are not the only way to contribute to open source projects. In addition, there are other GUI-friendly tools like GitHub Desktop that you can use instead. However, when you decide to take on an issue related to making changes to the source code, a basic understanding and experience with Git, Terminal and Vim can help you focus your time on solving the real issue rather than the tools used to manage code.
Before heading to your next open source hackathon or grabbing your first good first issue, try out the short tutorial leveraging the five tips to set yourself up for success!
Stay tuned to the Open Source Blog and follow us on Twitter for more deep dives into the world of open source contributing.
