Development/Git/Simple Workflow: Difference between revisions

    From KDE TechBase
    No edit summary
    No edit summary
    Line 1: Line 1:
    DANGER WILL ROBINSON!!!  THIS IS AN INCOMPLETE DRAFT!!!
    DANGER WILL ROBINSON!!!  THIS IS AN INCOMPLETE DRAFT!!!


    == Simple Workflow ==
    = 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 few weeks of using Git with KDE while you learn how Git works.  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 onto the Simple Feature Branch Workflow.


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


    More detailed information can be found on the main [[Development/Git|KDE Git page]].


    == Simple Feature Branch Workflow ==
    = 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 features in a manner similar to the old SVN 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.
    Line 14: Line 16:


    The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.
    The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.
    == Set-up ==
    This section documents how to set up Git and your code repository for development.
    === Configure Git ===
    Follow the [[Development/Git/Configuration|KDE Git Configuration]] page.
    === 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.
    To clone your project repository:
    cd your/source/dir
    git clone kde:<project>
    In our KFoo example:
    git clone kde:kfoo
    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:
    wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz
    == Basic Actions ==
    This section documents basic actions that are performed within your workflow.
    See also the [[Development/Git/Recipes|KDE Git Recipes]] page.
    === Create a Work Branch ===
    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:
    git branch <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.
    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>
    For our KFoo example:
    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, 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.
    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 [[http://techbase.kde.org/Development/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.


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

    Revision as of 13:04, 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 onto the Simple Feature Branch Workflow.

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

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

    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 features in a manner similar to the old SVN workflow.

    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.

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

    Set-up

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

    Configure Git

    Follow the KDE Git Configuration page.

    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.

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

    See also the KDE Git Recipes page.

    Create a Work Branch

    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:

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

    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>
    

    For our KFoo example:

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

    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.

    Set-up

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

    Configure Git

    Follow the KDE Git Configuration page.

    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.

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

    See also the KDE Git Recipes page.

    Create a Work Branch

    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:

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

    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>
    

    For our KFoo example:

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

    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.