Hello Fellow CodeNewbies ๐,
It's the last week of Hacktoberfest!
It's two days left by the time I'm writing this ๐.
If you are thinking of contributing, you still have time!
Last year, I wrote an article about how I contributed to open-source for the first time.
At that time, I needed to configure the remote repo that points to the upstream
. I also had to fetch and merge the upstream
from the command line to update the origin
repo.
But now, some things are becoming simpler with some GitHub features.
In this article, I will walk you through the flow in contributing to an open-source project.
Without further ado, let's do this! ๐ช
๐ Note on tools: I'm using GitHub site on browser and integrated bash terminal on VSCode.
1. Fork the original repo
First, we want to fork the original repo and not clone it right away.
Why do we want to fork the repo? You can find the answer in this article.
How to do this?
Go to the open-source's repo
Fork the repo by clicking on the "Fork" button on the right top of GitHub.
This forked repo is the origin
repo, while the original is the upstream
repo.
2. Clone the fork repo
Go to our repo list and open the forked repo.
Click the green "Code" button.
Choose from where we want to clone it and copy the link.
Open terminal/command line.
Direct it to the directory where we want to store the local repo with the
cd
command.Run
git clone <copied-link>
.
3. Create work/feature branch
We have the local repo, and we are ready to work on our changes.
But before doing so, we need to create a new branch to work on it. Don't make any changes in the main
/master
branch.
We can name our branch anything we want. For this example, I will call it working-branch-name
.
- Run
git checkout -b working-branch-name
.
This command creates a new branch namedworking-branch-name
and will direct us automatically to the branch.
4. Make the changes
We haven't finished making changes, but we want to call it a day
There are times when we haven't finished making our changes, and we want to continue working on it later on.
In other words, we are not ready to commit our changes.
Don't leave our work unsaved.
If we don't save or commit our changes, these changes can get carried onto other branches.
So what should we do?
Run
git stash
.
This command will save our changes and put the file in its original state just as before we make any changes.Run
git stash pop
.
This command will give back our saved work, and now we can continue to work on our changes.
However, we are encouraged to commit our changes as soon as we make some changes. It will benefit us to have a history of our changes to look back to.
We've finished making changes
- Run
git add .
This will add all changes that we made.
Alternatively,
Run
git add -p
.
We can pick which changes we want to stage, one by one. This command will display hunks of the file diff and ask us to stage them one by one.
You can read more about it here.Run
git commit -m "Our message of changes here"
.
5. Update our remote and local repo
We need to ensure that our original
and local repo has the same update as the upstream
before the push.
Go to our forked repo on GitHub.
We will see aFetch upstream
button on the right side.GitHub makes it easy for us to fetch the updates from the
upstream
.
Click this button, and we will get a dropdown menu.
When theFetch and merge
button is in inactive mode, there is no update on theupstream
. If it's green, click it.Our
origin
repo now has the same updates as theupstream
.Go to our terminal.
Go to our local
main
branch with thegit checkout main
command.Run
git pull
.
This command will fetch and merge the changes from themain
branch at theorigin
repo to the localmain
branch.Run
git status
.
This step ensures that our localmain
branch is up to date with themain
branch in theorigin
repo.
Our local main
branch now has the same updates as the origin
and upstream
.
Go to our branch with
git checkout <branch-name>
.Run
git merge main
.
You can read question no. 5 in this article if you get a conflict after merging a branch.
6. Push our changes to the original
repo
- Run
git push -u origin working-branch-name
.
This command tells to pushworking-branch-name
toorigin
repo.
7. Create pull request
Go to the
upstream
repo.Click the "Compare & pull request button".
It will redirect us to the "Open a pull request" form.
Fill the form with our changes as the title. Write the description of the changes in the body. Include here a reference to the issue as well.If we need some reviews from the maintainers before merging, we can make a draft of a pull request.
Click the arrow beside the "Create pull request" button to do this. It will give us the dropdown menu. Select the "Create draft pull request" and click the button. Otherwise, click the default "Create pull request" button.
8. Now, what next?
There is no next. That's it!
You've contributed to an open-source! ๐
Now you can wait for the maintainers to review your pull request ๐.
Thank you for reading!
Last but not least, you can find me on Twitter. Let's connect! ๐