For webcompat.com, we are developing the project using among others, the GitHub infrastructure. We have webcompat.com 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.
The project is hosted on
https://github.com/webcompat/webcompat.com/
I created a fork in my own area (the fork button at the top right)
https://github.com/karlcow/webcompat.com/
Now I can create a local clone on my computer.
git clone git@github.com: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 webcompat:master from karlcow:902/1.
https://github.com/webcompat/webcompat.com/pull/920
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 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
Otsukare!