otsukare Thoughts after a day of work

Documenting my git/GitHub workflow

For, we are developing the project using among others, the GitHub infrastructure. We have repository. Do not hesitate to participate.

I'm not sure we exactly share the same workflow in the core contributors, but I figured out that I should document the way I contribute. It might help beginners and it might be useful for myself in the future.

Let's start with a rough draft.

Git Workflow

The project is hosted on

I created a fork in my own area (the fork button at the top right)

Now I can create a local clone on my computer.

git clone

I'm cloning my fork instead of the project because I want to be able to work in local and mess up with branches that I push to my own fork without bothering anyone else. Pull requests are the moments I mingle with others.

Once I have done this. I have a fresh copy of the repo, I can start working on a issue. Let's take for example 902 (easy, dumb issue just for illustration). I create a new branch on my local clone. Read also below the section on updating my local fork.

git checkout -b 902/1

The protocol I use for the branch name (that I have stolen from Mike) is

branch_name = issue_number/branch_version

So if I'm not satisfied with the work done, but I still want to keep some history about it, I can create a second branch for this same issue with git checkout -b 902/2 and so on. When satisfied I will be able to pull request the one I really like.

git commit -m '#902 upgrade GitHub-Flask to 3.1.1' requirements.txt
git commit -m '#902 upgrade Flask-Limiter to 2.2.0' requirements.txt
# etc

At the end of the day or when I'm planning to do something or simply because I want to share the code. I will upload my work to my fork on github.

git push karlcow 902/1

Here you will notice that I didn't use git push origin 902/1, see below for the explanation about repository aliases.

Once I have finished with all the commits, I can create a pull request on GitHub to webcompat:master from karlcow:902/1.

I use the message:

fix #902 - 902/1 Update python module dependencies in the project.

and requests for a review by mike with

r? @miketaylr

We discuss, throw, modify or merge.

Repository aliases

Usually GitHub is using the terms upstream for the original repository and origin for your own fork. It was confusing me a lot so I decided to change that.

git remote rename origin karlcow
git remote rename upstream webcompat

It becomes a lot easier when I update the project or when I push my commits. I know exactly where it goes.

# download things from the repo on
git fetch webcompat
# pushing my branch to my own fork on
git push karlcow branch_name

Updating my local fork

Each time, I have finished with a branch or I have finished with today's work and everything has been committed. I keep my local (on my computer) clone master branch in synch with the distant master branch on

Usually with github vocabulary it is:

git checkout master
git fetch upstream
git merge upstream/master

In my case

git checkout master
git fetch webcompat
git merge webcompat/master

My project is updated and I can create a new branch for the next issue I will be working on.

Cleaning the local and remote forks

Because I create branches locally in ~/code/ and remotely on, it's good to delete them, little by little. So we do not end up with a huge list of branches when doing

git branch -a

For example right now, I have

git branch -a
* 710/3
  remotes/karlcow/HEAD -> karlcow/master

So to clean up I'll do this:

# Remove locally (on the computer)
git branch -d 12/1 245/1
# Remove remotely (on github my repo)
git push karlcow --delete 12/1
git push karlcow --delete 245/1