"Open source". Two words that when put together bring joy to a developer's heart. In fact, any tool or library you've used, is most likely open source. Which means that the entire code is freely available for anyone to view, download or even make a contribution to.
But what happens if you want to make your own contribution to a project you use and love? Maybe you want to fix a bug? Or add a new feature? Where does it all start and where does it end?
This article will describe the journey of an open source contribution, from issue to merge.
🗣️ This article is brought to you by Say Something. The project which helps you make your first open source contribution by making a very simple change. Check it out!
Station 1: The issue
Our journey starts here. On a website called Github. If a project is open source, chances are the code will live in this website, on its own page. Here's an example.
If you notice on the page, there's a tab called Issues.
This is where the bugs that need fixing, the typos that need correcting and the features that need building are located.
See an issue that you can work on? Great! On to the next step!
Station 2: The assignment
Before you can start working on an issue, the code maintainers have to put a label on the issue that you are going to work on it, so nobody else does. To do that, you'll have to reply to the issue saying something like "can I work on this issue?".
The maintainers would be more than happy to assign it to you, if they haven't already assigned it to someone else.
Now you can work on the issue!
Station 3: The fork
You now have the green light to work on the issue. But, you can't just work on the code on someone's else's account. You need to make a copy of it to your own account to start working. This is new copy is called a fork.
To do this, go to the repository page and click on the Fork icon on the top right.
You'll go to a page called Create a new fork.
You don't need to change anything. Just click on Create fork. After a few seconds, you'll have a copy of the whole code base of the project in your own account!
Now let's get to work!
Station 4: The clone
Now that you've copied the code to your account, it's time to download it to your computer, so you can work on it. The version of the code that will be on your computer is called a clone.
To clone the project, go to your copy of the code (your fork) and click the green Code button.
From the drop down menu, click the "copy" button.
The address of your repo will be copied to the clipboard.
Now head to your Terminal / or command prompt.
Before you proceed, you'll need to download Git. Once you do go to the terminal (or command prompt), go to the directory you want to copy the code and enter this command:
git clone <the address you copied>
For example:
git clone https://github.com/techforhumans/say-something.git
Once that's done, go to the directory of your code by using the cd command:
cd <project name>
For example:
cd say-something
Now let's make the changes!
Station 5: The code
Now you have the code in your computer and you're ready to open it and make changes using your favourite editor.
💡 If you don't have an editor yet, Visual Studio Code is a good one to download.
Navigate the code a bit to get familiarised with it and once you do, find the part of the code that has the issue, or where to add the new feature, or fix that typo.
💡 Some repositories have very specific contribution guidelines, with regards to how the code looks and what must be included in your contribution. Check the repository's README file or CONTRIBUTING file.
Station 6: The push
Once you're done with the changes and you're sure that your new code works, it's time to update your code on Github. We're doing this in 4 steps:
- Check
- Add
- Commit
- Push
Firstly, check your changed files. To do this, run this command:
git status
This will list all the files you've changed, created or deleted.
Next, we're going to "add" those changes. Basically it's a way of saying "I want these files to be pushed to my code on Github. This is the command:
git add -A
The above command basically says "I want all my changes to be pushed". Next we're going to "commit":
git commit -m "Added a dad joke"
...which basically means, keep the files I "added" safe until I push them.
And finally, you're going to push the changes. Simply do this:
git push
At this point you'll probably be asked to log in with your Github credentials (depending on the operating system) so they know it's you trying to push changes.
After that, if you go to your Github repository, your changes should show up there!
Now there's one more thing to do, and that's adding your changes to the actual code repository (ie. not your copy of it).
Station 7: The pull request
In order for your changes to end up on the actual code for the project, you'll have to show your changes to the code maintainers and ask them nicely for the changes to be included. We do this, with what we call a pull request.
To start, go to your fork of the code on Github and open the Pull requests tab.
Click on the green New pull request button.
Check your changes one last time and click the green Create pull request button.
On the Open a pull request page, add a short message (if one isn't present already) and click the Create pull request button.
Your pull request is ready!
Now what? Now... we wait... One of the code maintainers will check your pull request and approve it!
Last stop: The merge
If you come back to your pull request, and if a code maintainer is happy with your changes, you'll see this message
name approved these changes
Now, what's left is to merge your changes by clicking the green Merge pull request button.
That's it! 🎉
You have successfully made a contribution to the project! Your changes are proudly added to the main code of the whole project for the world to enjoy! Congrats!
If you're still reading up to this point, thank you! How did you find the article? Let me know below!
Check out my project Say Something to practice what you've just learned by making a very simple first contribution. See you there!
Top comments (0)