Git/Github Best Practices
Starting off your work on Github platform where a large number of community members are working on a project repository, there are certain points that you should keep in mind. Follow this simple guide - Git/Github best practices and things to remember while contributing to make your open source journey smoother.
1. Never Push Changes Directly to Main Branch
Always create a new branch while working on a project and commit those changes to that branch, pushing the code directly to the main branch will cause changes directly to the users using it and can crash the product due to number of reasons. So, it is better to create a new branch after you're done commiting the changes, merge with the main branch.
git command to create new branch :
bash
git branch new-branch
git checkout new-branch
The first command creates a new branch named new-branch and the second one puts the HEAD to the new branch, so all the commits after git checkout will occur on the new-branch. Once you're done with the changes just merge the new-branch to the main branch.
2. Fetch Updates
In open source there are lot of people contributing to a single repository. Therefore, make sure to fetch updates while you're creating/changing things. You don't want to make changes to outdated file, so before creating a new branch and working on that first synchronize your work with the parent repository.
git command for fetching updates :
git checkout main
git fetch upstream
git merge upstream/main
git push origin main
The first command will put the HEAD to the main branch, second one will fetch/download branches and commits from upstream repository to main branch of your forked repositiory. git merge command will integrate those fetched changes to your local forked repository, and at last git push will update the HEAD therby synchronizing your work
3. Don't Pile Up Work
Making huge changes in a single commit is not at all a good practice, doing so you're making sure that you're pull request gets on hold forever. I mean, just think about the reviewers how are they gonna review that never-ending code? So, always create commits in even small progress of your work, don't pile up that thing as it will create a mess. After that you can always squash those changes to a single commit with a good description.
git command to commit changes with a message :
git commit -m "your-message"
This will commit the recent staged changes with the message inside ""(double-quote) -m flag stands for message.
4. Pull Requests Clearance
Don't let those PRs stay for too long, try to merge them as soon as possible because unattended pull requests may land you in a big issue or conflict in the codebase. So, address and merge them at earliest. If the request is way too old to be addressed, tell the person who made the pull request to raise it again from a new branch.
git command to raise a pull request :
git push origin branch-name
This will push the changes into your forked repository. After this head back to your GitHub repository and click on Compare & pull request, this will land you in a page where you need to give title and description to your PR and then tap Create Pull Request
5. Stashing
Suppose while working on a branch you remembered that you need to work on another branch and you don't want to commit those changes in the first branch. No worries, git stash will help you sort that problem. It will save your work but not commit it, and you can come anytime on that branch and continue your work.
git stash command : This command will add all the changes that are not commited, staged or unstaged to the stash pile.
git stash
This will reapply those changes that you stashed previously.
git stash pop
6. Clean Commit Messages
Write a meaningful commit messages. Add in the description the changes you made on the commit in detail. Doing so, will help in future if you needed to check out specific changes that were made, you will be able to distinguish the work and save a lot of time. Think of a situation where some part of your code crashed and you have find out what changes made it crash, searching in those unmaintained/messy commits can be a headache. So, make sure you maintain those history in a good way.
7. Follow Community Guidlines
The most imported thing is to follow the guidlines and the code of conduct provided by the organization you are contributing. Check for their naming convention on certain files. Pull request and commit message formats, guidlines are created so the worflow remains steady and no conflicts takes places while managing the contributed files/work. It can be a major hit if you don't follow their guidlines you may even get banned from contributing further to the project. So, always respect the organizations protocals.
Hope you enjoyed ! Happy Contributing Geeks :)