-
Notifications
You must be signed in to change notification settings - Fork 29
FRED Git Workflow
Before getting started, please make sure that you have a recent version of git installed (>=1.7.10) otherwise you might run into problems like e.g. github https authentication errors (see https-cloning-errors and a solution using ssh). FRED2 follows basically the git-flow workflow which is documented here. The difference is that we do not create the merge commits locally (git flow feature finish) but manage these via pull requests. This document tries to give a short introduction into the basic workflow that we try to achieve. This document is subject to change, as we at some point may consider switching to a different strategy.
Every developer should start by creating its own fork on GitHub (see here). Your forked repository is called origin while upstream refers to the Fred2 repository. In contrast to your local repository, origin and upstream are remote repositories as they are hosted on github.
To obtain a local copy (your working copy) you now clone your fork with:
git clone https://github.com/_YOURUSERNAME_/Fred2.git
This will clone your fork (origin) into a local copy on your pc.
#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_/Fred2.git (fetch)
origin https://github.com/_YOURUSERNAME_/Fred2.git (push)
To be able to sync data between your local copy, your fork (origin) and the original Fred2 repository (upstream) you have to add FRED-2/Fred2 as upstream repository to your local repository. This can be done using the following command
git remote add upstream https://github.com/FRED-2/Fred2.git
You can verify that upstream was added correctly by calling
$ git remote -v
origin https://github.com/_YOURUSERNAME_/Fred2.git (fetch)
origin https://github.com/_YOURUSERNAME_/Fred2.git (push)
upstream https://github.com/FRED-2/Fred2.git (fetch)
upstream https://github.com/FRED-2/Fred2.git.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 the central Fred2 repo upstream.
git fetch upstream
git fetch origin
or shorter:
git fetch --all
Now you create a local develop branch (depending on your setup this branch has already been created and you will get notified).
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:
* develop 349ec48 Merge pull request #691 from cbielow/MGF_fix
feature/my_shiny_new_feature 3c05538 [FEATURE] added option to keep, ensure or reassign UIDs during conversion
remotes/origin/SILACAnalyzer 3ceae38 Fixed test.
remotes/origin/antilope 3fe5aa3 git-svn-id: https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/antilope@12117 6adb6e08-d915-0410-941f-83917bcadc18
remotes/origin/develop 349ec48 Merge pull request #691 from cbielow/MGF_fix
remotes/origin/master b182ba5 [NOP] first commit after SVN import to git
remotes/origin/msnovogen 93a5e4c [OPT] For faster access to specific amino acids a ResidueServer was added.
remotes/upstream/HEAD -> upstream/develop
remotes/upstream/antilope 3fe5aa3 git-svn-id: https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/antilope@12117 6adb6e08-d915-0410-941f-83917bcadc18
remotes/upstream/develop 349ec48 Merge pull request #691 from cbielow/MGF_fix
remotes/upstream/master b182ba5 [NOP] first commit after SVN import to git
It is advisable to keep your fork (origin) in sync with the Fred2 repository (upstream) (see here).
Quick reference for syncing: You typically fetch changes from (upstream) and update your local develop branch. Then you push your updated develop branch to your fork (origin). Instead of fetching only upstream we assume that you might additionally track other peoples repository so we use git 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 manually remove them in your local repository if they have been e.g. merged and deleted by their creator.
git fetch --all --prune
git checkout develop
git merge --ff-only upstream/develop
git push origin develop
In your individual fork you are free to change everything you like, but please keep in mind that everything that should be (at some point) merged back into Fred2 needs to fulfil certain quality standards (TODO: add some details).
To make your live easier you should follow some simple rules
-
never commit directly to the
developormasterbranches as it will complicate the merge - try to start every feature from
develop(see below) and not base features on other features (unless it is not avoidable) - name the Fred2 remote
upstreamand always push directly toorigin(git push origin <branch-name>) instead of relying on the default mechanism of git - when updating your fork consider using
git fetch upstreamfollowed bygit merge --ff-only upstream/developto avoid creating merge commits indevelop. If you never commit to develop this should always succeed and (if a commit accidentally went to develop) warn you instead of creating a merge commit.
All features start from develop.
git checkout develop
git checkout -b feature/your-cool-new-feature
All commits related to this feature will then go into the branch feature/your-cool-new-feature.
Note: This topic is subject to ongoing discussions. While working on your feature branch it is usual that development continues and new features get integrated into the main development branch. This means your feature branch lacks behind develop. To get your feature branch up to date you can rebase your feature branch on develop using:
git checkout feature/myfeaturebranch
git rebase develop
which basically:
- Performs a rewind of your commits until the branching point
- Applies all commits that have been integrated into
develop - Reapplies your commits on top of them see graphical graphical explanation of rebasing
as result, the history now looks as if your branch has just now been branched of from develop. 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 develop resulting in a linear history.
IMPORTANT: Do not rebase published branches (e.g. branches that are part of a pull request). If you made a pull request you should only add commits in your feature 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 develop without rebasing (see e.g. rebase-vs-merge).
Features that should go into the main development line of Fred2 should be integrated via a pull request. This gives the development community of Fred2 to discuss the changes and suggest possible improvements.
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 web site. Please note that origin is your fork and not the Fred2 repository.
Please open pull requests only if everything is tested and documented and all tests pass. Pull requests that do not fulfil those requirements will be rejected in favour of a maintainable and stable code base. A more detailed description of the requirements can be found here.
Starting a new release
After feature freeze merge develop into master and declare the RC1. After bug fixes, several RCs and stabilization the revision of the release is tagged.