Working with GitHub
What are Forks?
You can fork a repository you don't own.
That creates a copy of it under your account.
You can then use it as your own repository, and you can also use it to submit changes back to the original repository.
This is a very common flow for Open-Source Projects:
- A contributor will make a Fork of the Repository;
- Contributor will make changes to the code in their Fork;
- Contributor will submit the code changes back to the Repository;
- If changes are accepted, Contributor will close the Fork.
- If changes were not accepted, Contributor may make more changes to the Fork and submit changes again.
How to update your fork with new commits in the original repository
Sometimes you'll make a Fork and start making some changes, but then other people will make changes to the Original Repository.
You'll want to bring those changes into your Fork so that when you submit your changes, you are applying changes on top of the most up-to-date code (and not on the old code that was there when you made the Fork).
To do that, just navigate into your Fork repository and execute a git pull against the Original Repository:
git pull <url_of_original_repository>
Remember that at this point you may encounter Merge Conflicts. If so, you'll have to fix them as best as you can!
What are Pull Requests?
When the time comes to submit your code changes back to the Original Repository, you will create a Pull Request (also called Merge Request, and often abbreviated to PR or MR).
A PR or MR is a request to merge your changes into the Original Repository. It contains the changes you want to make to the code, and also provides a space for Contributors to have a conversation.
::: tip Think of and treat MRs as opportunities to have a conversation about the changes. That way, when someone makes comments about your code (such as pointing out mistakes, improvements, or request changes), they will feel less personal.
The objective of MRs is to improve the code in the Original Repository, so remember that when you're discussing the changes with other Contributors! :::
Making and responding to comments
Whether you're reviewing an MR that someone else made into your Repository, or you're making an MR into someone else's repository, you can make and respond to comments.
People will make comments in MRs for a variety of reasons:
- To suggest an improvement to the code;
- To ask why something was done, or why something was done in the way that it was;
- To point out a mistake;
Different people write comments in different ways, and sometimes it may feel like you are being personally attacked. This is often not the case, but some people are not as tactful as they could be.
My advice is to think the best of other people, and not take comments too personally! You are not your code, and even if it hurts your ego a little bit, difficult comments can be the ones that bring the most learning!
Similarly when you are responding to comments made in your MRs, be respectful and considerate. Try to reduce the amount of time and effort others have to put into reading your MRs by providing information and explanations upfront.
You can take that one step further, and write comments in your MR yourself before anyone else looks at it, explaining why you did certain things in the way you did; or what certain things mean. This can be really helpful for reviewers!
What are Issues?
Issues in GitHub are places to write down potential work to be done in a project. For example:
- Future improvements and features;
- Bug reports and potential fixes;
- Problems that users have encountered (which may end up as bug reports);
Some projects also use Issues as a way of handling Customer Support (i.e. if you have a problem with the project, you write it there and the Contributors help you out).
::: tip When you're creating an Issue in a Repository, remember to include as much detail as possible.
For example, when writing about a Bug you've found, you should include what happened, what you expected to happen, how it happened, how it can be reproduced by another Contributor, etc...
It takes a bit of experience to write Issues better, so don't worry if when you write them, Contributors come back to you with comments asking for more information. Just remember for next time! :::