[EN] Typical workflow with GitHub on shared project

Intro

I found this very strange, that all around the Internet there are lot of articles on how to do some extended techniques using git. But nowhere can find short, simple and easy recommendations on how to use GitHub to work on shared project.

This article is effort to describe typical workflow on shared project using git on GitHub.

For most of git-purposes I use console but not graphical interfaces. However, I have qgit and Cola git installed in my system.

What do we have?

There is some project you want to contribute to. For example, Mixxx. Project is hosted on GitHub.

To work on project you must have GitHub account and must have installed git on your working computer.

Development loop

Fork

Create fork of project using web-interface.
fork
So you’ll get forked project in your repositories list.
If your account name at GitHub is johndoe, you’ll get new repo called git clone https://github.com/johndoe/mixxx.git.
You can do everything you want with forked project. You can do any changes with it. That can’t hurt main (parent) project.

Local work

To get ability to work on project on local computer you must clone forked (on previous step) project.
As for me, that is very useful to hold all clones from different repositories in one folder like ~/Projects/working_copies. So we need to get into that folder (cd ~/Projects/working_copies) and apply command:

git clone https://github.com/johndoe/mixxx.git

This command will create new directory mixxx within all source codes got from https://github.com/johndoe/mixxx.git repository.

Of course, we want to update our repository’s codebase from parents’ one. So we need to “link” parents repository to ours:

git remote add upstream https://github.com/mixxxdj/mixxx.git

By default you are on master branch. You can check it using command

git branch

This command outputs list of available branches. Near one of branches there must be asterisk (*) — it means that you are on that branch.

If you are not at master branch, you can switch by next command:

git checkout master

And immediately update this branch according to (probably) new changes in parents’ repository:

git fetch upstream // got changes from upstream
git merge upstream/master // merge branch upstream/master with current (local master)

To upload all changes to your remote repository (do update of remote repo), you need to:

git push

provide login and password.

In this manner we can work on project adequately. Lots of developers advise do not touch master branch and do all changes into separate branch.

Branches

For switching between branches you can use

git checkout branch1

To create new branch (named newBranch by copying that branch you are standing on now):

git checkout -b newBranch

So, when you have local clone you must create new branch, named for example johndoe_fixes:

git checkout -b johndoe_fixes

Further, you must work on project at this branch. Here you must do all your commits.

For example, fix all changes with some message:

git commit -a -m "Fixes a ton of bugs..."

Your branch is only local branch (there is no such branch on your remote repo), you need upload this brunch to your remote repo:

git push origin johndoe_fixes

provide login and password.

Pull-request

If you have already done all steps described above then you can see fork at GitHub site in your repos. That fork will have branch johndoe_fixes.

You can choose that branch and track all changes. Also, here you can make request (to developers of parent project) to merge your changes with parent project. This procedure calls “pull request”. To avoid ambiguity, here “pull” means that developers of parent project will do git pull to your branch (got your changes and merge with parent’s master branch), of course, if your changes are adequate and will look good to developers.

To make pull-request you need open GitHub site -> your repo -> choose your branch -> on right vertical menu click “Pull requests”.
pull_request
Pull requests -> New pull request -> Edit.
Here, you must choose (if not was not chosen automatically) base fork: parents repo and its master branch: head fork: your repo, compare: respective branch — johndoe_fixes.
pull_request_branch

Do not forget comment your changes well.

After successful pull request, your branch will get on code review. Watch you e-mail box. Developers can discuss your changes. Be ready to have responsibility for your changes.

If your changes deserve to be merged with main project — your branch will be merged with master branch.

Summary

Quick review of all commands:

  • Fork project А on GitHub — into own projects (fork got address B).
  • git clone B
  • git remote add upstream А
  • git remote checkout master
  • git fetch upstream
  • git merge upstream/master
  • git push
  • git checkout -b newBranchFeatures
  • git commit -a -m "Added new features"
  • git push origin newBranchFeatures
  • Pull request.
  • Profit🙂

Have a nice commits and successful builds!

One thought on “[EN] Typical workflow with GitHub on shared project

  1. Сповіщення: Week 3. Mixxx codebase | GSoC-2013, Mixxx: Non-Blocking Database Access

Send feedback

Заповніть поля нижче або авторизуйтесь клікнувши по іконці

Лого WordPress.com

Ви коментуєте, використовуючи свій обліковий запис WordPress.com. Log Out / Змінити )

Twitter picture

Ви коментуєте, використовуючи свій обліковий запис Twitter. Log Out / Змінити )

Facebook photo

Ви коментуєте, використовуючи свій обліковий запис Facebook. Log Out / Змінити )

Google+ photo

Ви коментуєте, використовуючи свій обліковий запис Google+. Log Out / Змінити )

З’єднання з %s