Revision as of 13:35, 11 June 2011

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

Simple Workflow

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the Feature Branch Workflow.

In particular this workflow will not use git branches or any remote features, all feature work will be in the local master (the Git name for trunk).

The worked examples given will be for an imaginary app called KFoo in a git.kde.org code repository called 'kfoo'.

More detailed information can be found on the main KDE Git page.

Set-up

This section documents how to set up Git and your code repository for development.

Configure Git

Follow all the instructions on the KDE Git Configuration page, the instructions given below assume you are using the standard configuration.

Clone your repository

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>

In our KFoo example:

git clone kde:kfoo

See the KDE Build Environment page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to download a snapshot tarball to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

Basic Actions

This section documents basic actions that are performed within your workflow.

Making changes

Changing code is no different from when using subversion.

Seeing What You Changed

Committing Your Changes

Merging Your Changes

Local Feature Development

Local Bug Fixing

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any depth. If possible it is recommended you wait until you are familiar with using the Feature Branch Workflow.

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable. A more efficient method is detailed in the Feature Branch 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 stable4.6 origin/KDE/4.6
git checkout stable4.6
<make changes, build, test>
git commit -a
<make note of sha5 of commit>
git pull --rebase
git push origin stable4.6:KDE/4.6
git checkout master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git pull --rebase
git push origin master:master

@@ Line 3: / Line 3: @@
 = Simple Workflow =
-This workflow is designed to be as close as possible to the KDE SVN Workflow.  It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands.  Once comfortable with the basic commands you should then move onto the Simple Feature Branch Workflow.
+This workflow is designed to be as close as possible to the KDE SVN Workflow.  It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands.  Once comfortable with the basic commands you should then move on to the [[Infrastructure/Git/Feature_Branch_Workflow|Feature Branch Workflow]].
-The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.
+In particular this workflow will not use git branches or any remote features, all feature work will be in the local master (the Git name for trunk).
+The worked examples given will be for an imaginary app called KFoo in a git.kde.org code repository called 'kfoo'.
 More detailed information can be found on the main [[Infrastructure/Git|KDE Git page]].
@@ Line 15: / Line 17: @@
 === Configure Git ===
-Follow the [[Infrastructure/Git/Configuration|KDE Git Configuration]] page.
+Follow all the instructions on the [[Infrastructure/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.
 === Clone your repository ===
-You need to copy your repository from git.kde.org into your local KDE source directory.  In Git this process is called cloning.
+You need to copy your central code repository from git.kde.org into your local KDE source directory.  In Git this process is called cloning.
 To clone your project repository:
@@ Line 32: / Line 34: @@
 See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.
-If you have a slow internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone.  You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:
+If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone.  You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:
   wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz
@@ Line 42: / Line 44: @@
 See also the [[Infrastructure/Git/Recipes|KDE Git Recipes]] page.
-=== Create a Work Branch ===
+=== Making changes ===
-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.
-To see what local branches you have:
- git branch
-To see all local and remote branches:
- git branch -a
-To create a new local branch:
+Changing code is no different from when using subversion.
- git branch <new-branch>
+=== Seeing What You Changed ===
- 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.
-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:
- git branch --track <local-branch> <remote-branch>
+=== Committing Your Changes ===
-For our KFoo example:
+=== Merging Your Changes ===
- 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.
+If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.
-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, the KFoo app may have the following branches on the central repository:
- origin/master
- origin/feature/hot-new-stuff
- origin/feature/cool-newer-stuff
- origin/release/1.0
- origin/release/1.1
- origin/release/2.0
-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.
+If your bug fix is for a stable branch then this cannot be done without using git branches.  The steps required will be given below but not explained in any depth.  If possible it is recommended you wait until you are familiar with using the [[Infrastructure/Feature_Branch_Workflow|Feature Branch Workflow]].
-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.
+The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable.  A more efficient method is detailed in the [[Infrastructure/Feature_Branch_Workflow|Feature Branch Workflow]].
-=== 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 branch --track stable4.6 origin/KDE/4.6
-  git checkout bug-fix-2.0
+  git checkout stable4.6
   <make changes, build, test>
   git commit -a
-  git push origin bug-fix-2.0:release/2.0
+ <make note of sha5 of commit>
-  git branch --track bug-fix-master origin/master
+  git pull --rebase
-  git checkout bug-fix-master
+  git push origin stable4.6:KDE/4.6
+  git checkout master
   git cherry-pick -x -e <sha5 of stable commit>
   <build, test>
-  git push origin bug-fix-master:master
+ git pull --rebase
+  git push origin 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 [[http://techbase.kde.org/Infrastructure/Git/Configuration#Multiple_Work_Branches|git-new-workdir 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.