Our GitHub workflow

Creating your fork

Every developer should start by creating its own fork on GitHub (see here). Your forked repository is called origin while upstream refers to the PSI-QC repository. In contrast to your local repository, origin and upstream are remote repositories as they are hosted on GitHub.

Cloning your fork

To obtain a local copy (your working copy) you now clone your fork with:

$ git clone https://github.com/_YOURUSERNAME_/qcML-development.git

This will clone your fork (origin) into a local copy on your computer. If you are using a Desktop client, this and the following steps might be taken over by the software.

Configuring communication with remote branches in your local working repository

After cloning from your fork, your local repository should only know about your fork and it should be named origin. You can validate this by executing

$ git remote -v
origin	https://github.com/_YOURUSERNAME_/qcML-development.git (fetch)
origin	https://github.com/_YOURUSERNAME_/qcML-development.git (push)

To be able to sync data between your local copy, your fork (origin) and the original repository (upstream) you have to add HUPO-PSI/qcML-development as upstream repository to your local repository. Adding an upstream repository can be done using the following command

$ git remote add upstream https://github.com/HUPO-PSI/qcML-development.git

You can verify that upstream was added correctly by calling

$ git remote -v
origin	https://github.com/_YOURUSERNAME_/qcML-development.git (fetch)
origin	https://github.com/_YOURUSERNAME_/qcML-development.git (push)
upstream	https://github.com/OpenMS/qcML-development.git (fetch)
upstream	https://github.com/OpenMS/qcML-development.git (push)

If everything worked as expected, you should be able to fetch changes and new branches from your fork (origin) as well as from upstream.

$ git fetch upstream
$ git fetch origin

or shorter:

$ git fetch --all

As you cloned your fork, at least one local branch should have been created, your local master branch. Now you can create a local branch, to work on.

$ git checkout -b develop

You can always call git branch -va to display the status of local and remote branches. You should see an output that contains all local branches, the branches on origin and upstream.

Keeping your fork in sync

It is advisable to keep your fork (origin) in sync with the HUPO-PSI repository (upstream) (see here).

Quick reference for syncing: You typically fetch changes from (upstream) and update your local branch(es). Then you push the updated branch(es) back to your fork (origin). Instead of fetching only upstream we assume that you might additionally track other peoples repository so we use get fetch --all --prune to update them as well. The option '--prune' tells git to automatically remove tracked branches if they got removed in the remote repository. This means you don't need to remove them manually in your local repository if they have been e.g. merged and deleted by their creator.

$ git fetch --all --prune
$ git checkout master
$ git merge --ff-only upstream/master
$ git push origin master

In your own fork you are free to change everything you like, but please keep in mind that everything that should be (at some point) merged back. Some simple guidelines will make that easier:

• never commit directly to the master branch as it will complicate the merge
• try to start every feature from master (see below) and not base a branch on another branch
• name the remote upstream and always push directly to origin (git push origin <branch-name>) instead of relying on the default mechanism of git
• when updating your fork consider using git fetch upstream followed by git merge --ff-only upstream/master to avoid creating merge commits in master. If you never commit to master this should always succeed and (if a commit accidentally went to master) warn you instead of creating a merge commit.

Start a new feature

All features start from master.

$ git checkout master
$ git checkout -b metric/your-cool-new-metric

All commits will now go into that branch. It may help keeping track to prefix your branch with a tiny topic or scope-of-edit description like metric/.

Keeping your branch in sync with master branch (and origin)

While working on your branch, development usually continues. This means your branch may lack behind upstream/master. To get your branch up to date, sync your fork and rebase your branch on master using:

$ git checkout metric/your-cool-new-metric
$ git rebase master

which basically:

1. Performs a rewind of your commits up to the branching point
2. Applies all commits that have been integrated into master
3. Reapplies your commits on top of them

See this graphical explanation of rebasing.

As a result, the history now looks as if your branch has just now been branched off from master. As a nice side effect of this rebase as cleanup is that your feature branch can now be merged by fast forward (=just applying your commits directly without actual merge) into master resulting in a linear history.

IMPORTANT: Do not rebase published branches (e.g. branches that are part of a pull request).

Finish a feature

A branch finished should be integrated via a pull request to HUPO-PSI/qcML-development. If your branch is addressing an issue from the issue list, you can directly reference it while requesting the pull by writing the issues number (e.g. #1) in the pull request description. This gives the community the opportunity to read up on the issue, discuss the changes and suggest possible improvements. If you made a pull request, you could still add commits in your branch to fix things that came up e.g. in discussions of the pull request.

After your pull request contains all fixes you are ready to merge the pull request into master without rebasing (see e.g. rebase-vs-merge).

Opening a pull request is quite easy and discussed in the linked article. The short version is

$ git push origin feature/your-cool-new-feature

Followed by opening the pull request via the GitHub website.