Infrastructure/Git/Feature Branch Workflow: Difference between revisions

From KDE Community Wiki
(Created page with 'THIS IS A DRAFT, DO NOT USE! = Simple Feature Branch Workflow = This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new...')
 
m (21 revisions imported)
 
(20 intermediate revisions by 2 users not shown)
Line 1: Line 1:
THIS IS A DRAFT, DO NOT USE!
THIS IS A DRAFT, DO NOT USE!


= Simple Feature Branch Workflow =
= Feature Branch Workflow =


This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new features in a manner similar to the old SVN 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.


Note that each module may choose to adopt a more complex workflow and you should check with your modules maintainers if this is the case.
This workflow is designed to be used after initial use of the [[Infrastructure/Git/Simple_Workflow|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.


The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.
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 [[Infrastructure/Git|KDE Git page]]. More details on the various commands can be found on the [[Infrastructure/Git/Recipes|KDE Git Recipes]] page.


== Set-up ==
== Set-up ==


This section documents how to set up Git and your code repository for development.
See the [[Infrastructure/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository


=== Configure Git ===
== Local Feature Development ==


Follow the [[Infrastructure/Git/Configuration|KDE Git Configuration]] page.
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.


=== Clone your repository ===
=== Create a Local Work Branch ===


You need to copy your repository from git.kde.org into your local KDE source directory.  In Git this process is called cloning.
To see what local branches you have:


To clone your project repository:
git branch


cd your/source/dir
This will initially appear as follows, with the * indicating your current working branch:
git clone kde:<project>


In our KFoo example:
* master


git clone kde:kfoo
To see all local and remote branches:


See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.
git branch -a


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:
This will initially look something like:


  wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz
  *  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


== Basic Actions ==
To create a new local branch:


This section documents basic actions that are performed within your workflow.
git branch <new-branch>
 
Now running <tt>git branch</tt> will show:


See also the [[Infrastructure/Git/Recipes|KDE Git Recipes]] page.
*  master
    my-new-branch


=== Create a Work Branch ===
To change to the new branch to work on it:


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.
  git checkout <new-branch>


To see what local branches you have:
Now running <tt>git branch</tt> will show:


  git branch
    master
  *  my-new-branch


To see all local and remote branches:
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.


  git branch -a
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:


To create a new local branch:
git branch --track <local-branch> <remote-branch>


git branch <new-branch>
For example to develop a new feature called 'bar' based on the central repository master 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.
git branch --track new-bar-feature origin/master


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:
=== Making Changes ===


git branch --track <local-branch> <remote-branch>
You can now make [[Infrastructure/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Infrastructure/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Infrastructure/Git/Simple_Workflow|Simple Workflow]].


For our KFoo example:
Your project may require changes to be reviewed before pushing to the central code repository.  All projects on git.kde.org automatically have a [[Infrastructure/Review_Board|Review Board]] group created for them which you can use for this purpose.  It is recommended that you use the [[Infrastructure/Review_Board#Using_post-review_to_post_changes_for_review|post-review script]] to automatically generate and upload the diff of your changes.


git branch --track new-bar-feature origin/master
=== Deleting Local Branches ===


=== Commit Your Changes ===
Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.


=== Push Your Changes ===
First, you have to change to a different branch:


== Local Feature Development ==
git checkout master


This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.
Then you can delete the feature branch:


This workflow is only recommended for small features or where you are the only developer on a project.
git branch -d <local-branch>


== Remote Feature Development ==
== Remote Feature Development ==


This example workflow is for working on new features in a feature branch hosted on the central repository.
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.
 
The main disadvantage of local feature branch development is no-one else can see your code changes or help you until the finished feature is pushed to master on the central repository.  You could resolve this by regularly pushing incomplete features to master, but this will lead to master becoming more unstable.  The proper solution is to create a Remote Feature Branch on the central repository where you can push your interim work for others to see and also push changes to.


This workflow is recommended for larger features or where there are many developers on a project.
TODO: Finish this.
 
TODO Steps:
* Create the remote branch tracking master
  git push origin master:refs/heads/<remote-branch>
  git fetch origin
* Create your local branch tracking the remote branch
  git branch --track <local-branch> origin/<remote-branch>
  git checkout <local-branch>
* Do local dev and commits, rebase, push
* When to use Merges, when to Rebase?
* Once local commits are pushed you cannot rewrite them!


== Local Bug Fixing ==
== Local Bug Fixing ==
Line 89: Line 111:
This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.
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, the KFoo app may have the following branches on the central repository:
In Git, stable branches are just regular branches that have special meaning to a project and possibly a special naming scheme to distinguish them.  For example, kdelibs includes the following branches on the central repository:


origin/master
  origin/HEAD -> origin/master
origin/feature/hot-new-stuff
  origin/KDE/4.5
origin/feature/cool-newer-stuff
  origin/KDE/4.6
origin/release/1.0
  origin/kdecore/klocale-win
origin/release/1.1
  origin/kdeui/kdatetimeedit
origin/release/2.0
  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.
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.
In the [[Infrastructure/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.
 
=== 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
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.
  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 ===
One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.


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.
A better alternative is to use the [[Infrastructure/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.


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.
TODO: Finish this.

Latest revision as of 12:50, 9 March 2016

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

Making Changes

You can now make local changes and commits, and push them to the central repository exactly as described in the Simple Workflow.

Your project may require changes to be reviewed before pushing to the central code repository. All projects on git.kde.org automatically have a Review Board group created for them which you can use for this purpose. It is recommended that you use the post-review script to automatically generate and upload the diff of your changes.

Deleting Local Branches

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git branch -d <local-branch>

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.

The main disadvantage of local feature branch development is no-one else can see your code changes or help you until the finished feature is pushed to master on the central repository. You could resolve this by regularly pushing incomplete features to master, but this will lead to master becoming more unstable. The proper solution is to create a Remote Feature Branch on the central repository where you can push your interim work for others to see and also push changes to.

TODO: Finish this.

TODO Steps:

  • Create the remote branch tracking master
 git push origin master:refs/heads/<remote-branch>
 git fetch origin
  • Create your local branch tracking the remote branch
 git branch --track <local-branch> origin/<remote-branch>
 git checkout <local-branch>
  • Do local dev and commits, rebase, push
  • When to use Merges, when to Rebase?
  • Once local commits are pushed you cannot rewrite them!

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 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.

In the Simple Workflow bug fixing section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

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.

One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.

A better alternative is to use the git-new-workdir script to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.

TODO: Finish this.