I recently started collaborating and maintaining a project on Github. In this blog, I shared my workflow to keep the GitHub collaboration smooth for both contributors and maintainers.✨
Contributors
Never work on the main
branch!, If you think this is a minimal change, I would do it in the main branch and create a PR, Please Don't.
If you work on the main
branch, It won't be easy for you to keep up with the upstream
since the commit history of upstream main
would become different from your fork and create problems for you.
By main
, I mean the branch against which you will be creating PR.
Contributing
- Create a fork
- Clone your fork locally using
git clone https://github.com/your_username/repo_name
- Add the original repository as remote upstream to your local repository
git remote add upstream https://github.com/owner_username/repo_name
Make sure your local main branch is in sync with upstream
run the following command in your main branchgit pull upstream main
NOTE: Never make a commit directly to the main branch
Create a new branch
patch-11
frommain
and check out 'patch-11'. You can use any name for your branch.git branch patch-11
git checkout patch-11
💡 Time for a small task
We can use a shortcut to run the above task in just one command, i.e., creating a new branch and checking out the new branch. Find out what it is, and let me know in the comments.Work on
patch-11
. Commit your changes.- Push your commits to the origin.
- Open your pull request from the
patch-11
branch against themain
branch of the original repository. - Pat yourself on the back and wait for your pull request to be reviewed and merged.
- If there are any merge conflicts, you can resolve them in GitHub itself or use your IDE.
- As soon as your PR gets merged, delete the
patch-11
branch. It's useless now. - For the next contribution, sync your local main branch with upstream and get to work again by creating a new branch.
Resolving Conflicts
You can resolve small conflicts in GitHub itself or you can use your favorite IDE to resolve conflicts. mine is VS Code.
- Checkout to the
patch-11
branch. - Pull upstream main, All conflicts will be revealed, Resolve them using the GUI of your favorite IDE, doing it in CLI is certainly not a good idea. I use VS Code and it has amazing in built features to resolve merge conflicts.
- After you successfully resolve all the conflicts, commit the changes and push them to origin.
- Pat yourself on the back again! You did it.🎉
Maintainers
First things first, disable merge commits
Go to the settings of your repository, scroll down to Merge Button option and uncheck ''Allow merge commits".
Allowing merge commits make the commit history bit messy. I would recommend using Squash and Merge option to merge Pull Requests. Squash and Merge combines all commits in PR into one and adds it to main
branch.
Why squash and merge?
If I made a Pull Request and commits are as shown below
We don't want both these commits to showing up in the commit history main branch. The second commit 'formatted' won't make any sense in the commit history of the main
branch.
When commits are merged with a merge commit, the commit history looks like this -
Instead of the six different commits for a single PR dedicated to one issue, We want just one commit with a clear commit message. Apart from making the commit history linear, It would make contributions more smooth for everyone.
On using squash and merge, the commit history looks much better and is understandable.
See the screenshot below 👇
Thank You for Reading, this was the first blog I wrote, I would love to get your feedback in the comments🙃.