Basic Git Contribution Workflow
Git can be complicated. There are forks, branches, commits, rebases (oh, my!). Git is also the language necessary to contribute to open source, so learning the basics is well worth the effort. The following is a basic git workflow to contribute to any open source project using git version control. The examples throughout this post demonstrate making a contribution to the n8n project.
1 - Fork the Repository
The first step is to fork the project that you want to contribute to. A fork basically makes a copy of the repository that you can then modify. In Github, you simply click the fork button on the main repository page:
After the forking process is complete, you’ll have your own forked repository to work off of:
Click the button to copy the Clone HTTPS URL. We’ll use it in the next step.
2 - Clone the Fork
Now that you have forked the repository, the next step is to clone the fork onto your development machine. Cloning will copy the code onto your computer so you can modify it locally. To clone, we’ll run the
git clone command in the terminal:
git clone https://github.com/jonmbake/n8n.git
3 - Add Upstream Remote
Remotes are used to reference your fork and the main repository (living on github.com) from your local clone. The remote that the repository was cloned from automatically gets set to
origin. To make it easier to
git fetch or
git pull changes from the main repository, it’s useful to set a remote to the main repository URL, which will call
upstream by convention. To do this run
git remote add upstream:
git remote add upstream https://github.com/n8n-io/n8n.git
4 - Check Out the Development Branch
You’ll be submitting a pull request to a development branch. Checkout the branch you’re going to be submitting a pull request to. Usually,
master is the branch under current development:
git checkout master
It’s also a good idea to
git pull to ensure you are working off of the most recent changes:
git pull upstream master
5 - Create a Feature Branch Off of the Development Branch
The next step is to create a branch where you will do your work. This can be done via
git checkout -b:
git checkout -b fix-1364-mouse-selection-zoom
It’s a good idea to name your feature branch as a short description of the change you intend to make. In this case, I am fixing a bug with mouse selection when zoomed.
6 - Make Some Code Changes, Add and Commit
Now you’re all set to start coding! Make some changes, stage the code changes by running
git add and then commit:
git add . git commit -m 'Fixes #1364 - Incorrect mouse selection when zoomed in or out'
Pro tip: Make sure to break up larger changes into smaller commits with good commit messages.
Pro tip 2: In Github, by prefacing your commits with “Fixes”, “Fixed”, “Fix”, “Closes”, “Closed”, or “Close” when the commit is merged, it will automatically link to the issue from the commit and close the issue when merged.
7 - Push Your Changes
Once your code changes are committed, you can push your commits up to your fork, i.e.
git push origin fix-1364-mouse-selection-zoom
Which will output the URL to create the pull request:
Projects/n8n - (fix-1364-mouse-selection-zoom) > git push origin fix-1364-mouse-selection-zoom Enumerating objects: 5, done. Counting objects: 100% (5/5), done. Delta compression using up to 8 threads Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 326 bytes | 326.00 KiB/s, done. Total 3 (delta 2), reused 0 (delta 0) remote: Resolving deltas: 100% (2/2), completed with 2 local objects. remote: remote: Create a pull request for 'fix-1364-mouse-selection-zoom' on GitHub by visiting: remote: https://github.com/jonmbake/n8n/pull/new/fix-1364-mouse-selection-zoom remote: To https://github.com/jonmbake/n8n.git * [new branch] fix-1364-mouse-selection-zoom -> fix-1364-mouse-selection-zoom
At this step, we can navigate to the pull request URL.
8 - Submit the Pull Request
The final step in this journey is to submit a pull request. As with commit messages, provide a detailed explanation of the change to the code reviewer:
9 - Making Further Changes Based on Code Review
Code reviewers may request additional changes. No problem! Just push further commits up to the
origin feature branch and they will automatically get added to the existing pull request.
If changes are made on the main development branch while you are working on your feature, it will get behind. In which case, you can fetch/pull from upstream and rebase onto your feature branch to “sync up the branches”:
git checkout master git pull upstream master git checkout fix-1364-mouse-selection-zoom git rebase master git push origin fix-1364-mouse-selection-zoom -f
See a typo? Submit a Pull Request.