Infrastructure/Git/Feature Branch Workflow: Difference between revisions
| Line 17: | Line 17: | ||
== Local Feature Development == | == Local Feature Development == | ||
By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes. | |||
=== Create a Work Branch === | === Create a Local Work Branch === | ||
To see what local branches you have: | To see what local branches you have: | ||
git branch | git branch | ||
This will initially appear as follows, with the * indicating your current working branch: | |||
* master | |||
To see all local and remote branches: | To see all local and remote branches: | ||
git branch -a | git branch -a | ||
This will initially look something like: | |||
* master | |||
remotes/origin/HEAD -> origin/master | |||
remotes/origin/KDE/4.5 | |||
remotes/origin/KDE/4.6 | |||
remotes/origin/kdecore/klocale-win | |||
remotes/origin/kdeui/kdatetimeedit | |||
To create a new local branch: | To create a new local branch: | ||
git branch <new-branch> | git branch <new-branch> | ||
Now running <tt>git branch</tt> will show: | |||
* master | |||
my-new-branch | |||
To change to the new branch to work on it: | To change to the new branch to work on it: | ||
| Line 38: | Line 55: | ||
git checkout <new-branch> | git checkout <new-branch> | ||
This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes. | Now running <tt>git branch</tt> will show: | ||
master | |||
* my-new-branch | |||
This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes. | |||
You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches: | You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches: | ||
git branch --track <local-branch> <remote-branch> | git branch --track <local-branch> <remote-branch> | ||
For example to develop a new feature called 'bar' based on the master branch: | For example to develop a new feature called 'bar' based on the central repository master branch: | ||
git branch --track new-bar-feature origin/master | git branch --track new-bar-feature origin/master | ||
Revision as of 18:30, 12 June 2011
THIS IS A DRAFT, DO NOT USE!
Feature Branch Workflow
This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.
This workflow is designed to be used after initial use of the Simple Workflow. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.
Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.
More detailed information can be found on the main KDE Git page. More details on the various commands can be found on the KDE Git Recipes page.
Set-up
See the Simple Workflow Set-up section for instructions on configuring Git and Cloning your Repository
Local Feature Development
By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.
Create a Local Work Branch
To see what local branches you have:
git branch
This will initially appear as follows, with the * indicating your current working branch:
* master
To see all local and remote branches:
git branch -a
This will initially look something like:
* master remotes/origin/HEAD -> origin/master remotes/origin/KDE/4.5 remotes/origin/KDE/4.6 remotes/origin/kdecore/klocale-win remotes/origin/kdeui/kdatetimeedit
To create a new local branch:
git branch <new-branch>
Now running git branch will show:
* master my-new-branch
To change to the new branch to work on it:
git checkout <new-branch>
Now running git branch will show:
master * my-new-branch
This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.
You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:
git branch --track <local-branch> <remote-branch>
For example to develop a new feature called 'bar' based on the central repository master branch:
git branch --track new-bar-feature origin/master
Commit Your Changes
Push Your Changes
Local Feature Development
This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.
This workflow is only recommended for small features or where you are the only developer on a project.
Remote Feature Development
This example workflow is for working on new features in a feature branch hosted on the central repository.
This workflow is recommended for larger features or where there are many developers on a project.
Local Bug Fixing
This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.
In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:
origin/HEAD -> origin/master origin/KDE/4.5 origin/KDE/4.6 origin/kdecore/klocale-win origin/kdeui/kdatetimeedit origin/master
Here origin/KDE/4.6 is the 4.6 release of kdelibs.
Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.
Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.
Basic Bug Fix Workflow
To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:
git branch --track bug-fix-2.0 origin/release/2.0 git checkout bug-fix-2.0 <make changes, build, test> git commit -a git push origin bug-fix-2.0:release/2.0 git branch --track bug-fix-master origin/master git checkout bug-fix-master git cherry-pick -x -e <sha5 of stable commit> <build, test> git push origin bug-fix-master:master
Advanced Bug Fix Workflow
the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.
This workflow uses the [script] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.