Difference between revisions of "Development/Tutorials/Git/Feature Development Workflow/Simple Branch Development"

Jump to: navigation, search
(Created page with '[http://www.example.com link title]{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress ...')
 
 
(14 intermediate revisions by 4 users not shown)
Line 1: Line 1:
[http://www.example.com link title]{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project. }}
+
{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project. }}
  
This tutorial is aimed to get casual developers or developers with limited git knowledge started for developing their own branches, and get them merged and integrated.
+
This tutorial can help casual developers as well as developers with a limited knowledge of git to get started quickly. It covers the entire work flow, from developing in branches to getting them merged and integrated for the next release.
  
 
This tutorial does not require any git-specific knowledge.
 
This tutorial does not require any git-specific knowledge.
Line 7: Line 7:
 
Before you start, you are strongly advised to read the following documents:
 
Before you start, you are strongly advised to read the following documents:
  
* Which repository should I use?
+
* [[Development/Tutorials/Git/Feature_Development_Workflow/Repository_Roles|Which repository should I use?]]
  
 
===Repositories and projects complying with this policy===
 
===Repositories and projects complying with this policy===
Line 17: Line 17:
  
 
===Rationale===
 
===Rationale===
This approach is meant to implement proper quality evaluation into the main repositories, still allowing developers to work on anything they want, and providing a sane merging strategy which does not require any specific knowledge from the developer's side.
+
The approach described in this document helps us implement proper quality evaluation for code that ends up in the main repositories while still allowing developers to work on anything they want. It provides a sane merging strategy which does not require any special git knowledge from the contributing developer's side.
  
 
To learn more about the rationale behind this approach, please read [[Development/Tutorials/Git/Feature_Development_Workflow/Rationale|the Rationale article]].
 
To learn more about the rationale behind this approach, please read [[Development/Tutorials/Git/Feature_Development_Workflow/Rationale|the Rationale article]].
  
 
===Setting up the development environment===
 
===Setting up the development environment===
In the following steps, we will assume your system is set up as shown in the [http://community.kde.org/Sysadmin/GitKdeOrgManual git.kde.org user manual], especially regarding  [http://community.kde.org/Sysadmin/GitKdeOrgManual#Let_Git_rewrite_URL_prefixes automatic URL rewriting for KDE repositories] enabled.
+
The following steps assume your system is set up as shown in the [http://community.kde.org/Sysadmin/GitKdeOrgManual git.kde.org user manual], especially regarding  [http://community.kde.org/Sysadmin/GitKdeOrgManual#Let_Git_rewrite_URL_prefixes automatic URL rewriting for KDE repositories] enabled.
  
 
In the following tutorial, we'll refer to kdelibs as the main target, but this applies to any other repository using this policy.
 
In the following tutorial, we'll refer to kdelibs as the main target, but this applies to any other repository using this policy.
  
 
====Cloning the repository and adding integration====
 
====Cloning the repository and adding integration====
 +
 +
=====The Recipe=====
 +
<syntaxhighlight lang="bash">git clone kde:kdelibs
 +
git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration
 +
git fetch integration</syntaxhighlight>
 +
 +
=====The Explanation=====
 +
 
To clone the repository, issue
 
To clone the repository, issue
  
git clone kde:kdelibs
+
<syntaxhighlight lang="bash">git clone kde:kdelibs</syntaxhighlight>
  
 
This will create a kdelibs directory containing the whole repository. You now need to add a separate remote for handling ''integration''. A remote is a repository URL, and your local clone can contain multiple repositories to track different branches. To add kdelibs' ''integration'' repository, issue inside kdelibs' clone:
 
This will create a kdelibs directory containing the whole repository. You now need to add a separate remote for handling ''integration''. A remote is a repository URL, and your local clone can contain multiple repositories to track different branches. To add kdelibs' ''integration'' repository, issue inside kdelibs' clone:
  
git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration
+
<syntaxhighlight lang="bash">git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration</syntaxhighlight>
  
 
Now, fetch from integration to retrieve the changes:
 
Now, fetch from integration to retrieve the changes:
  
git fetch integration
+
<syntaxhighlight lang="bash">git fetch integration</syntaxhighlight>
  
 
{{note|When working with multiple remotes, you can issue ''git fetch --all'' to update all the remotes tracked by your local copy }}
 
{{note|When working with multiple remotes, you can issue ''git fetch --all'' to update all the remotes tracked by your local copy }}
Line 47: Line 55:
  
 
This command creates a local branch set to track a remote one. This branch should be the branch you'll be basing your work upon: origin/master is not meant for development!
 
This command creates a local branch set to track a remote one. This branch should be the branch you'll be basing your work upon: origin/master is not meant for development!
 
{{note|Advanced users might want to use ''integration'' as their origin }}
 
  
 
====Using integration vs. using your own clone====
 
====Using integration vs. using your own clone====
Line 61: Line 67:
 
  git checkout integration-master
 
  git checkout integration-master
  
Now create your branch. Give it a self-explainatory name: try to keep branches as atomic as possible, and possibly split big changes throughout multiple branches divided as per topic. In our case, we want to name our branch ''add-hello-button''. To do that, we do:
+
Now create your branch. Give it a self-exeplainatory name: try to keep branches as atomic as possible, and possibly split big changes throughout multiple branches divided as per topic. In our case, we want to name our branch ''add-hello-button''. To do that, we do:
  
 
  git checkout -b add-hello-button
 
  git checkout -b add-hello-button
Line 69: Line 75:
 
  git push integration add-hello-button
 
  git push integration add-hello-button
  
====Getting the branch reviewed====
+
====Synchronizing the branch with master====
Once you are done with your changes, you are ready to get your branch reviewed. This involves three easy steps:
+
When you create a branch (like you did), you are not receiving incremental updates from other people working in the repository (so in the ''master'' branch). This is usually not an issue, and instead an advantage: you can work on your code without being affected by other changes.
  
=====Rebase your branch onto integration/master=====
+
However, there are some cases in which ''synchronizing'' your code with what's been going on with master is required. Git gives you two ways for doing that: merging or rebasing.
It is important to have your branch rebased to be ready for review. Rebasing puts your commits on top of anything else of the branch you are rebasing on, including the changes from that branch. You of course want to rebase onto ''integration/master''. To do that, issue
+
  
git rebase integration/master
+
When you are working on a separate branch, you always want to merge instead of rebasing, which should be done only at the end of the branch's lifecycle. A merge can be performed with:
  
Be sure to fetch before doing that. At this stage, conflicts might occur: be sure to fix them and commit/push the result. You will be required to force push at this stage.
+
git fetch --all
 +
git merge integration/master
  
{{warning|Rebasing must be done at this stage only: please avoid rebasing before getting reviewed or after getting reviewed if not strictly necessary }}
+
This command merges your work with the very latest code from ''integration/master''. Please note that you must merge '''only''' the branch you originated from (integration/master) into your repository: merging a different branch corrupts history and might prevent rebases to succeed.
 +
 
 +
To learn more about merging, rebasing, and what this implies to your branch and to our merge strategy, you are invited to read [[Development/Tutorials/Git/Feature_Development_Workflow/Rebase_vs_Merge|Rebasing vs. merging: why and how]]
 +
 
 +
====Getting the branch reviewed====
 +
Once you are done with your changes, you are ready to get your branch reviewed. In the review process, the project's core developers will evaluate your code's quality, and will help you in making it perfect before it gets integrated. Here's how to do it.
  
 
=====Push your changes to integration=====
 
=====Push your changes to integration=====
Line 86: Line 97:
 
  git push integration add-hello-button
 
  git push integration add-hello-button
  
from within your ''add-hello-button'' branch. If you do not have one, please have your mentor push your branch for you.
+
from within your ''add-hello-button'' branch.
 +
 
 +
If you do not have a KDE Developer account, please get in touch with the core developer who is mentoring you, or with one of the repository's maintainers to get your changes pushed into ''integration''.
  
 
=====Submit the branch for review=====
 
=====Submit the branch for review=====
Use Reviewboard for getting your branch reviewed. You can read [http://techbase.kde.org/Development/Review_Board KDE Reviewboard+Git tutorial] for getting started.
+
Use Reviewboard for getting your branch reviewed. You can read [[Development/Review_Board|KDE Reviewboard+Git tutorial]] for getting started and understanding the steps involved.
 +
 
 +
It is '''critical''' that you specify in the review request whether your branch has ever been merged with master or not.
 +
 
 +
=====Modifying the branch=====
 +
Everytime you update your review request with new code, please remember to push changes to ''integration'' with your new code. That will help developers in reviewing and maintainers in handling your request.
 +
 
 +
====Getting your branch integrated====
 +
Once your review request has been marked as "Ship it!", your job is done. The maintainers will take care of merging the branch into ''integration/master'', stage it for release, and make it reach ''origin'' in the end.
  
====Getting the branch approved====
+
It is '''critical''' at this point to have your branch ''frozen''. You should not commit anything else to your branch and you should consider it dead. Maintainers will take over its commits and will delete it when merging occurs.
After your branch has been reviewed and marked as "Ship it!" at least by one of the maintainers of the code you are adding features to, your branch is ready for integration and staging. Your reviewer will inform one of the repository's maintainers of that.
+
  
Your work is done at this stage: the maintainer will integrate and stage your branch for you, and will merge it into ''origin'' according to the project's merging policy. You will be CCMailed upon every separate step your branch will take on its way to ''origin/master''
+
If you are curious to find out what happens to your commit after your code is accepted, read [[Development/Tutorials/Git/Feature_Development_Workflow/Merge_Strategies|Merge strategies to and from integration]]

Latest revision as of 20:42, 24 March 2012

noframe
 
Warning
This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project.


This tutorial can help casual developers as well as developers with a limited knowledge of git to get started quickly. It covers the entire work flow, from developing in branches to getting them merged and integrated for the next release.

This tutorial does not require any git-specific knowledge.

Before you start, you are strongly advised to read the following documents:

Contents

[edit] Repositories and projects complying with this policy

The following repositories/projects follow these guidelines. Any project not mentioned here is unaffected by what described

  • kde-workspace
  • kde-runtime
  • kdelibs (plasma only)

[edit] Rationale

The approach described in this document helps us implement proper quality evaluation for code that ends up in the main repositories while still allowing developers to work on anything they want. It provides a sane merging strategy which does not require any special git knowledge from the contributing developer's side.

To learn more about the rationale behind this approach, please read the Rationale article.

[edit] Setting up the development environment

The following steps assume your system is set up as shown in the git.kde.org user manual, especially regarding automatic URL rewriting for KDE repositories enabled.

In the following tutorial, we'll refer to kdelibs as the main target, but this applies to any other repository using this policy.

[edit] Cloning the repository and adding integration

[edit] The Recipe
git clone kde:kdelibs
git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration
git fetch integration
[edit] The Explanation

To clone the repository, issue

git clone kde:kdelibs

This will create a kdelibs directory containing the whole repository. You now need to add a separate remote for handling integration. A remote is a repository URL, and your local clone can contain multiple repositories to track different branches. To add kdelibs' integration repository, issue inside kdelibs' clone:

git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration

Now, fetch from integration to retrieve the changes:

git fetch integration
noframe
 
Note
When working with multiple remotes, you can issue git fetch --all to update all the remotes tracked by your local copy

[edit] Creating branches

You now need to get your branches set up, in particular integration/master. In this example, we are creating a new branch named integration-master which would serve for this purpose in particular:

git checkout -b integration-master integration/master

This command creates a local branch set to track a remote one. This branch should be the branch you'll be basing your work upon: origin/master is not meant for development!

[edit] Using integration vs. using your own clone

It is strongly advised to push your work to integration, but under some circumstances (your work is extremely big in size, you do not have a KDE Development account, etc.), it is allowed to push your branches to a separate personal clone. All work should end up into integration for being reviewed anyway.

[edit] Developing a new feature

We'll now walk through the process needed to develop a new feature. We'll suppose you want to add a button which says "hello" to a specific part of code.

[edit] Creating a new branch

First thing to do is creating a new branch on which to base your work on. This branch must be based upon integration/master. To make sure this happens, start by issuing

git checkout integration-master

Now create your branch. Give it a self-exeplainatory name: try to keep branches as atomic as possible, and possibly split big changes throughout multiple branches divided as per topic. In our case, we want to name our branch add-hello-button. To do that, we do:

git checkout -b add-hello-button

That will create our personal branch which is going to contain our work. Push your branch to integration by issuing

git push integration add-hello-button

[edit] Synchronizing the branch with master

When you create a branch (like you did), you are not receiving incremental updates from other people working in the repository (so in the master branch). This is usually not an issue, and instead an advantage: you can work on your code without being affected by other changes.

However, there are some cases in which synchronizing your code with what's been going on with master is required. Git gives you two ways for doing that: merging or rebasing.

When you are working on a separate branch, you always want to merge instead of rebasing, which should be done only at the end of the branch's lifecycle. A merge can be performed with:

git fetch --all
git merge integration/master

This command merges your work with the very latest code from integration/master. Please note that you must merge only the branch you originated from (integration/master) into your repository: merging a different branch corrupts history and might prevent rebases to succeed.

To learn more about merging, rebasing, and what this implies to your branch and to our merge strategy, you are invited to read Rebasing vs. merging: why and how

[edit] Getting the branch reviewed

Once you are done with your changes, you are ready to get your branch reviewed. In the review process, the project's core developers will evaluate your code's quality, and will help you in making it perfect before it gets integrated. Here's how to do it.

[edit] Push your changes to integration

If you have a KDE developer account, simply

git push integration add-hello-button

from within your add-hello-button branch.

If you do not have a KDE Developer account, please get in touch with the core developer who is mentoring you, or with one of the repository's maintainers to get your changes pushed into integration.

[edit] Submit the branch for review

Use Reviewboard for getting your branch reviewed. You can read KDE Reviewboard+Git tutorial for getting started and understanding the steps involved.

It is critical that you specify in the review request whether your branch has ever been merged with master or not.

[edit] Modifying the branch

Everytime you update your review request with new code, please remember to push changes to integration with your new code. That will help developers in reviewing and maintainers in handling your request.

[edit] Getting your branch integrated

Once your review request has been marked as "Ship it!", your job is done. The maintainers will take care of merging the branch into integration/master, stage it for release, and make it reach origin in the end.

It is critical at this point to have your branch frozen. You should not commit anything else to your branch and you should consider it dead. Maintainers will take over its commits and will delete it when merging occurs.

If you are curious to find out what happens to your commit after your code is accepted, read Merge strategies to and from integration


This page was last modified on 24 March 2012, at 20:42. This page has been accessed 3,260 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal