Contributing to free software / open source projects using github and/or gitlab and/or pagure.io

There’s lots of information on how to use git on the internet. There’s lots of different ‘flows’. Git-flow, Github-Flow, and possibly others that don’t have such a cool name.

Names aside, I’m going to outline the ‘flow’ I use git with public repos such as gitlab and github when I want to contribute to a free software project. There’s nothing new or original here, just clear and concise instructions.

TLDR: Fork. Clone Fork. Don’t use ‘pull’ use ‘fetch’ for getting changes from upstream. Switch to a remote tracking branch e.g. upstream/master, create feature branch from that remote tracking branch directly, push new feature branch to origin (aka your fork).

Step One: Fork the repository

This is the first step. It’s not 100% mandatory, but it makes life a little easier. It will create a copy of an entire software project to your personal space on the service. On github.com, I created another org I call ‘<username>-upstream-stage’ to fork projects into in an effort to keep my personal area on github dedicated to my own projects. This is optional and may or may not suite your needs.

Step Two: Clone your fork to your development workstation

Just as the title says, clone the fork to your workstation. This will setup the first ‘git remote’ called ‘origin’. Remote names are arbitrary, but using your personal fork as origin helps keep things consistent.

Step Three: Add ‘upstream’ remote

Again, remote names are arbitrary but it’s common practice to name the official repository that you want to pull updates from and send Pull/Merge requests ‘upstream’.

Step Four: Fetch ‘upstream’

This is where some people will choose a different path. I no longer ‘pull’ from upstream and try to merge into my fork’s master branch. I just set up the remote tracking branches using fetch.

Step Five: Create feature branch

To create a feature branch, checkout a remote tracking branch. IE, ‘git checkout upstream/master’. Next, create a new branch: ‘git checkout -b my-new-feature’. Commit some changes, push new feature branch to origin. ‘git push origin my-new-feature’

Step Six: Create PR/MR

Create a pull or merge request on the community site.

Extra bits

From time to time, your feature branch might go stale and you might need to merge in changes from upstream. Don’t worry, I’ve got you covered.

Step One: Fetch ‘upstream’

Just as it says. Nothing fancy to do here.

Step Two: Rebase on upstream remote tracking branch

You want to checkout your feature branch if you’re not still on it. Rebase it with ‘git rebase upstream/master’

If there are any merge conflicts, you will have to manually fix them, but this is IMO the correct way to go about it.

Step Three: Push to origin

You’ll notice, we’re not trying to update all the other branches in origin; we don’t care about those branches for this process. We just need to push our feature branch to origin. This will update any existing pull / merge requests that are in queue and re-trigger any integration tests the project has enabled.

When should I use pull?

To Deploy Software Updates

If you are deploying software to your prod/dev/etc environments via source using git, this is an appropriate time to use pull. It will update your local branch with updates from origin (or whatever remote your specify).

When you have more than one development workstation

This should be fairly uncommon, but it is definitely possible. You might want to pull changes from origin into your local working branch if you’ve made updates somewhere else and pushed them back to your repo. This may or may not prove to be the easiest/best practice depending on your circumstances.

Show your support

Clapping shows how much you appreciated Michael Gugino’s story.