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.
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 firstname.lastname@example.org:karlcow/webcompat.com.git
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
I use the message:
fix #902 - 902/1 Update python module dependencies in the project.
and requests for a review by mike with
We discuss, throw, modify or merge.
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 webcompat.com repo on github.com git fetch webcompat # pushing my branch to my own fork on github.com 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 webcompat.com.
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/webcompat.com/ and remotely on
https://github.com/karlcow/webcompat.com/, 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 264/1 396/1 * 710/3 713/1 master r929/958 remotes/karlcow/264/1 remotes/karlcow/702/1 remotes/karlcow/710/1 remotes/karlcow/710/3 remotes/karlcow/HEAD -> karlcow/master remotes/karlcow/master remotes/webcompat/gh-pages remotes/webcompat/issues/741/2 remotes/webcompat/letmespamyou remotes/webcompat/master remotes/webcompat/searchwork remotes/webcompat/staging remotes/webcompat/staticlabels remotes/webcompat/webpack
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